v2.0.0 Documentation fixpointforge.dev
● FORGE v2.0.0 — Stable

The Convergent
Normalization Engine

FORGE intercepts, validates, and repairs AI-generated content before it reaches downstream systems. Diffs, JSON, prompts, compliance text, speech transcripts, video metadata — all normalized through a fixpoint convergent loop that iterates until output stabilizes or fails closed.

7 Content Types
20 Normalizer Lanes
HMAC SHA-256 Attestation

Install in Seconds

pip install fixpointforge
Python 
from forge import normalize_content

result = normalize_content("your AI-generated content", "TEXT")
print(result.passed)            # True if normalization succeeded
print(result.normalized_content) # The cleaned output
print(result.audit_trail)        # Per-lane results and timing
⚡

New to FORGE? The Quick Start guide walks through installation, your first normalization call, and understanding ForgeResult in under 5 minutes.

Single Entry Point

Every interaction with FORGE starts with normalize_content(content, content_type). This function accepts raw content (a string, dict, or structured object) and a content type identifier. It returns a ForgeResult containing the normalized output, an audit trail of every lane that ran, per-lane results, and a boolean passed flag.

The result also carries a ForgeStamp — an HMAC-SHA256 sealed attestation that records the actor info, which lanes executed, and the final trust level. Downstream consumers can verify the stamp to make policy decisions without re-running normalization.

Documentation

⚡ Quick Start Install FORGE and normalize your first piece of content in under 5 minutes. Understand ForgeResult fields. ⚙ī¸ Configuration Every ForgeConfig field — env vars, YAML keys, defaults, and per-lane overrides. 📄 Content Types All 7 content types — DIFF, TEXT, JSON, PROMPT, COMPLIANCE, SPEECH, VIDEO_META — with lane routing diagrams. 🛤ī¸ Lanes Complete reference for every normalizer across 20 files in forge/normalizers/. Before/after examples for each. đŸ“Ļ Python API Full reference for normalize_content(), ForgeResult, ForgeStamp, ForgeConfig, and all public classes. 🏗ī¸ Architecture Fixpoint loop internals, convergence detection, lane interaction, failure modes, and attestation flow. 📡 Telemetry FailureRecord schema, what's collected, anonymization, the self-improving loop, and how to opt out.

Three Core Guarantees

  1. Normalization — Malformed, unsafe, or policy-violating content is repaired to a valid state where possible. If repair fails, FORGE quarantines or rejects the content with a clear trust signal.
  2. Attestation — Every output carries a ForgeStamp with HMAC-SHA256 signature and a trust level (TRUSTED, REPAIRED, QUARANTINED, or REJECTED) so consumers know exactly what happened.
  3. Observability — Structural failure telemetry is collected (never raw content) and optionally uploaded to telemetry.fixpointforge.report to drive continuous normalizer improvements.

FORGE sits at the boundary of any AI pipeline — between an LLM and your database, between a code-generation model and your CI system, between a speech model and your audio infrastructure, or between a compliance engine and your regulatory reporting layer.

Key Concepts

Concept Description
Lane A single normalizer that handles one concern (e.g., PII redaction, hunk header repair, JSON schema validation). Lanes are chained per content type. FORGE ships 20 normalizer files in forge/normalizers/.
Fixpoint Loop FORGE runs lanes repeatedly until the output stops changing (converges) or a failure threshold is reached. This is the core of the "convergent normalization" model.
ForgeResult The output of normalize_content() — includes normalized_content, audit_trail, lane_results, content_type, and passed.
ForgeStamp Cryptographic attestation sealed with HMAC-SHA256. Contains actor info, which lanes ran, and the final trust level. Tamper-evident by design.
Trust Level TRUSTED = passed clean; REPAIRED = fixed and converged; QUARANTINED = suspicious but emitted; REJECTED = failed closed.
ForgeConfig Configuration loaded from environment variables (FORGE_*) or forge_config.yaml. Controls lane enablement, convergence thresholds, telemetry, and more.
Content Type One of 7 types that determines which lane chain executes: DIFF, TEXT, JSON, PROMPT, COMPLIANCE, SPEECH, or VIDEO_META.
Telemetry Structural failure metadata (never raw content) collected via forge/telemetry/ and optionally uploaded to the FORGE cloud for self-improvement.

Lane Routing at a Glance

Each content type has a specific lane chain. Here's the routing overview:

DIFF

L0 → L0.5 → L0.7 → Loop: L1→L2→L3→L4

TEXT

T0 → Loop: T1→T2→T3→T4

JSON

T1 → Loop: T2→T3→T4

PROMPT

T2

COMPLIANCE

T3 → T0 → T4

SPEECH

S0 → T0 → Loop: T1→T2→T3→T4

VIDEO_META

T1 → V0 → V1 → T4
ℹī¸

SP (Service Provider) lanes are outbound only — they apply when FORGE emits content to external services. See Lanes for the full reference.

Project Structure

forge/
├── __init__.py              # normalize_content() entry point
├── config.py                # ForgeConfig loader
├── result.py                # ForgeResult + ForgeStamp
├── normalizers/             # 20 normalizer lane files
│   ├── l0_syntax.py
│   ├── l05_hunk.py
│   ├── l07_context.py
│   ├── l1_structure.py
│   ├── l2_semantic.py
│   ├── l3_compliance.py
│   ├── l4_attestation.py
│   ├── t0_encoding.py
│   ├── t1_schema.py
│   ├── t2_prompt_safety.py
│   ├── t3_policy.py
│   ├── t4_final.py
│   ├── s0_speech.py
│   ├── v0_video_struct.py
│   ├── v1_video_meta.py
│   └── ...                  # 5 additional utility normalizers
├── telemetry/
│   ├── collector.py         # FailureRecord creation
│   ├── uploader.py          # Upload to telemetry.fixpointforge.report
│   └── anonymizer.py        # Content stripping
└── loop.py                  # Fixpoint convergent loop engine