ngeodesic

Geometry-First AI Reasoning Engine
Shapes latent geometry to suppress hallucinations and stabilize multi-step plans.

---

Why ngeodesic?

Modern LLMs are great at language but drift under pressure. ngeodesic adds a geometry-first reasoning layer that treats model latents like a physical system:

• Warp the manifold to a single dominant “well” (funnel)
• Detect true signals with matched filters + statistically calibrated nulls
• Denoise phantom wells with hybrid smoothing, inhibition guards, and jitter averaging

Use it as a standalone parser/validator or pair it with a small micro-LLM sidecar (e.g., for DeFi, ARC-like tasks, coding, or tool plans, etc.).

---

Install

# Core (lightweight)
pip install ngeodesic==0.0.2a1

# With optional extras
pip install "ngeodesic[ml]"      # scikit-learn: PCA/whitening
pip install "ngeodesic[viz]"     # matplotlib/scipy: plots
pip install "ngeodesic[dev]"     # pytest, ruff, mypy, etc.

Python ≥ 3.10 recommended.

---

Quickstart

import numpy as np
from ngeodesic.core.denoise import TemporalDenoiser
from ngeodesic.core.parser import geodesic_parse_report
from ngeodesic.core.matched_filter import half_sine_proto

rng = np.random.default_rng(42)
n, T = 3, 160
traces = [np.clip(rng.normal(0, 0.3, T) + (i==1)*np.sin(np.linspace(0, np.pi, T)), -2, 2)
          for i in range(n)]

keep_mask, order = geodesic_parse_report(traces, sigma=9, proto_width=64)

# ema_decay=0.85  -> ema_alpha = 1 - 0.85 = 0.15
den = TemporalDenoiser(method="hybrid", ema_alpha=0.15, hybrid_k=3)
smoothed = den.smooth(np.array([0.1, 0.4, 0.8, 0.6, 0.7], dtype=float))

print("Detected:", keep_mask, "Order:", order)
print("Smoothed:", smoothed)

Tip: In LLM workflows, feed traces from a stable hidden-state “tap” (e.g., layer −9, last-k tokens). The parser/denoiser is model-agnostic.

---

Stage-11 quickstart

pip install ngeodesic  # or pip install -e .
ngeodesic-stage11-demo
# expect: truth [1, 2] / pred [1, 2] / keep [False, True, True]

---

## Core ideas (1-minute tour)

- **Warp**: Project latents to PCA(3), fit a radial **funnel** profile, and compute curvature/depth metrics.  
- **Detect**: Build per-primitive residual channels, run a **unimodal matched filter**, gate with dual thresholds (relative vs best channel, absolute vs **null** from circular shifts or permutations).  
- **Denoise**: Hybrid EMA+median smoothing, **phantom-guard** local probes, and **jitter averaging** to enforce stable, repeatable decisions.

---

## API overview

```python
# Parser / detection
from ngeodesic.core.parser import (
    stock_parse,                  # simple baseline
    geodesic_parse_report,        # Stage-10 parser
    geodesic_parse_with_prior,    # Stage-11 (optional priors/funnel)
)

# Funnel & warp
from ngeodesic.core.pca_warp import pca3_and_warp
from ngeodesic.core.funnel_profile import (
    fit_radial_profile, analytic_core_template, priors_from_profile
)

# Denoising & guards
from ngeodesic.core.denoise import TemporalDenoiser, phantom_guard, snr_db

# Sidecar (micro-LLM hooks)
from ngeodesic.sidecar.hooks import ModelHooks   # Protocol interface
from ngeodesic.sidecar.runner import Runner      # Minimal loop runner

---

Typical LLM pattern

1. Encode a prompt/context with output_hidden_states=True (e.g., GPT-2-medium).
2. Tap a stable layer (e.g., −9), slice the last-k tokens (e.g., 160).
3. Detect candidate primitives with geodesic_parse_report(...).
4. Denoise/guard to suppress phantoms and late flips.
5. Execute confirmed steps in your domain layer (e.g., DeFiPy, ARC primitives, tool calls).

---

Status & roadmap

• Status: pre-release 0.1.0a1 (APIs stabilizing; tests/docs in progress).
• Next: finalize parser.py Stage-11 path, add DeFi synthetic generator, and ship examples.
• Micro-LLM research: lives in a separate fast-iteration repo; hardened pieces will fold back here as ngeodesic.micro.*.

---

License & notice

• License: Apache-2.0 (see LICENSE).
• Notice: repository may reference methods described in the NGF provisional filings. Publishing the code under Apache-2.0 does not grant a patent license.

---

Patents

This code implements methods described in the Noetic Geodesic Framework (NGF) provisional filings: #63/864,726; #63/865,437; #63/871,647; #63/872,334 (all Aug 2025). Publishing under Apache-2.0 does not grant any patent rights beyond those expressly provided by that license. :contentReference[oaicite:0]{index=0}

---

Citation (optional)

If this work helps your research or product, please cite:

@software{ngeodesic,
  title   = {ngeodesic: Geodesic Reasoning Engine for LLMs},
  author  = {Moore, Ian C.},
  year    = {2025},
  url     = {https://pypi.org/project/ngeodesic/}
}