Quick Start

Go from zero to normalized content in under 5 minutes.

---

Step 1 — Install FORGE

FORGE is available on PyPI. Install it with pip:

pip install fixpointforge

For development or to pin a specific version:

# Pin to v2.0.0
pip install fixpointforge==2.0.0

# Install with optional telemetry dependencies
pip install fixpointforge[telemetry]

# Install from source
git clone https://github.com/fixpointforge/forge.git
cd forge
pip install -e .

---

Step 2 — Your First Normalization

The entire FORGE API is a single function: normalize_content(content, content_type). It accepts raw content and a content type string, runs the appropriate lane chain, and returns a ForgeResult.

Python

from forge import normalize_content

# Normalize a plain text string
result = normalize_content(
    content="Hello   world!!  This has   extra   spaces.",
    content_type="TEXT"
)

print(result.passed)              # True
print(result.normalized_content)  # "Hello world!! This has extra spaces."
print(result.content_type)        # "TEXT"

That's it — five lines to install, import, call, and inspect the result.

---

Step 3 — Understanding ForgeResult

Every call to normalize_content() returns a ForgeResult object. Here are all the fields you'll work with:

Inspecting the full result

from forge import normalize_content

result = normalize_content("Some AI-generated text...", "TEXT")

# Check overall pass/fail
if result.passed:
    print("Content is safe to use")
    print(result.normalized_content)
else:
    print("Content was rejected or quarantined")

# Inspect the audit trail
for entry in result.audit_trail:
    print(f"  Lane: {entry.lane_id}")
    print(f"  Status: {entry.status}")
    print(f"  Duration: {entry.duration_ms}ms")
    print(f"  Changes: {entry.changes_made}")
    print()

# Check a specific lane
if "T2" in result.lane_results:
    t2 = result.lane_results["T2"]
    print(f"Prompt safety: {t2.status}")
    print(f"Issues found: {t2.issues}")

---

Step 4 — The ForgeStamp

Every ForgeResult carries a ForgeStamp — an HMAC-SHA256 sealed attestation that cryptographically proves what happened during normalization. This is how downstream systems verify that content was actually processed by FORGE.

Accessing the stamp

result = normalize_content(content, "TEXT")

stamp = result.stamp

# Trust levels: TRUSTED, REPAIRED, QUARANTINED, REJECTED
print(stamp.trust_level)   # "REPAIRED"

# Which lanes executed
print(stamp.lanes)         # ["T0", "T1", "T2", "T3", "T4"]

# Actor information (who/what invoked FORGE)
print(stamp.actor)         # {"service": "my-api", "version": "1.2.0"}

# Cryptographic seal — verify with your HMAC secret
print(stamp.signature)     # "a3f8c1..."
print(stamp.verify())      # True

Trust Levels Explained

---

Step 5 — Try Different Content Types

FORGE supports 7 content types, each with its own lane chain:

Normalizing a Diff

Python

diff_content = """--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
 # My Project
+
 This is the readme.
 It has multiple lines."""

result = normalize_content(diff_content, "DIFF")
# Runs: L0 → L0.5 → L0.7 → Loop(L1 → L2 → L3 → L4)
print(result.passed)  # True

Normalizing JSON

Python

json_content = {
    "name": "test",
    "value": None,        # Will be validated
    "extra_field": "..."  # Schema enforcement
}

result = normalize_content(json_content, "JSON")
# Runs: T1 → Loop(T2 → T3 → T4)
print(result.normalized_content)

Normalizing Speech Transcripts

Python

speech = "uhh so like the the meeting is at 3pm tomorrow"

result = normalize_content(speech, "SPEECH")
# Runs: S0 → T0 → Loop(T1 → T2 → T3 → T4)
print(result.normalized_content)
# "The meeting is at 3pm tomorrow"

Normalizing Video Metadata

Python

video_meta = {
    "title": "My Video",
    "duration_seconds": 120,
    "chapters": [
        {"start": 0, "end": 60, "title": "Intro"},
        {"start": 60, "end": 120, "title": "Main Content"}
    ]
}

result = normalize_content(video_meta, "VIDEO_META")
# Runs: T1 → V0 → V1 → T4
print(result.passed)

---

Step 6 — Configuration

FORGE loads configuration from environment variables or a YAML file. The simplest way to get started:

Environment Variables

export FORGE_HMAC_SECRET="your-secret-key"
export FORGE_TELEMETRY_ENABLED=true
export FORGE_MAX_ITERATIONS=10
export FORGE_LOG_LEVEL=INFO

forge_config.yaml

forge:
  hmac_secret: "your-secret-key"
  max_iterations: 10
  log_level: INFO
  telemetry:
    enabled: true
    endpoint: "https://telemetry.fixpointforge.report"
  lanes:
    L0:
      enabled: true
    T2:
      strict_mode: true

Environment variables take precedence over YAML. See Configuration for every available field.

---

Next Steps