Python API Reference

Complete reference for all public functions and classes in FORGE v2.0.0.

---

normalize_content()

The primary entry point for all FORGE normalization. Accepts content and a content type, runs the appropriate lane chain, and returns a ForgeResult.

Parameters

Returns

Returns a ForgeResult instance with the normalized content, audit trail, lane results, and ForgeStamp.

Raises

Python — basic usage

from forge import normalize_content

# Simple call
result = normalize_content("Hello world", "TEXT")

# With custom config
from forge.config import ForgeConfig
config = ForgeConfig(max_iterations=20, strict_mode=True)
result = normalize_content(data, "JSON", config=config)

# With actor override
result = normalize_content(content, "DIFF", actor={
    "service": "code-review-bot",
    "version": "2.1.0",
    "environment": "production"
})

---

ForgeResult

Returned by normalize_content(). Contains all outputs of the normalization pipeline.

Attributes

Methods

Serialize the entire result to a JSON-compatible dictionary.

Serialize to a JSON string.

Human-readable summary: trust level, lanes run, iteration count, timing.

Python

result = normalize_content(content, "TEXT")

# Quick summary
print(result.summary())
# "TEXT | REPAIRED | 3 iterations | 4 lanes | 12.3ms"

# Full serialization
data = result.to_dict()
json_str = result.to_json(indent=2)

# Check convergence
if not result.converged:
    print(f"Did not converge after {result.iterations} iterations")

---

ForgeStamp

Cryptographic attestation sealed with HMAC-SHA256. Attached to every ForgeResult as result.stamp.

Attributes

Methods

Verify the HMAC-SHA256 signature. Uses the provided secret or falls back to FORGE_HMAC_SECRET.

Serialize the stamp to a JSON-compatible dictionary.

Serialize to a compact string suitable for HTTP headers (X-Forge-Stamp).

Class method. Deserialize a stamp from its header representation.

Python

stamp = result.stamp

# Verify signature
assert stamp.verify()  # Uses FORGE_HMAC_SECRET from env
assert stamp.verify(secret="my-custom-secret")

# Use in HTTP headers
response.headers["X-Forge-Stamp"] = stamp.to_header()

# Reconstruct from header
received_stamp = ForgeStamp.from_header(request.headers["X-Forge-Stamp"])
if received_stamp.verify():
    print(f"Trust level: {received_stamp.trust_level}")
else:
    print("Stamp verification failed — content may be tampered")

---

ForgeConfig

Configuration container. Loads from constructor args, environment variables, and YAML file.

Constructor Parameters

All configuration fields are accepted as keyword arguments. For example:

config = ForgeConfig(
    hmac_secret="secret",
    max_iterations=10,
    telemetry_enabled=True,
    strict_mode=False,
    log_level="INFO"
)

Methods

Check if a specific lane is enabled.

Get lane-specific configuration dict.

Check if a content type is enabled.

Get max iterations for a content type (falls back to core setting).

Override a config value at runtime.

Override a lane-specific config value at runtime.

Validate the configuration. Returns a list of error strings (empty if valid).

Serialize the resolved configuration to a dictionary (secrets are masked).

---

AuditEntry

A single entry in the audit trail, representing one lane execution.

---

LaneResult

Aggregate result for a single lane across all iterations.

---

Exceptions

Python — error handling

from forge import normalize_content
from forge.exceptions import (
    ForgeError,
    ForgeConfigError,
    ForgeTimeoutError,
    ForgeContentError,
    ForgeLaneError
)

try:
    result = normalize_content(content, "TEXT")
except ForgeTimeoutError as e:
    print(f"Timed out after {e.elapsed_ms}ms")
    # Partial result may be available
    if e.partial_result:
        print(f"Partial: {e.partial_result.summary()}")
except ForgeContentError as e:
    print(f"Bad content: {e}")
except ForgeLaneError as e:
    print(f"Lane {e.lane_id} failed: {e}")
except ForgeError as e:
    print(f"FORGE error: {e}")

---

Module Structure

# Main entry point
from forge import normalize_content

# Configuration
from forge.config import ForgeConfig

# Result types
from forge.result import ForgeResult, ForgeStamp, AuditEntry, LaneResult

# Exceptions
from forge.exceptions import (
    ForgeError,
    ForgeConfigError,
    ForgeTimeoutError,
    ForgeContentError,
    ForgeLaneError
)

# Content type constants
from forge.types import (
    DIFF, TEXT, JSON, PROMPT,
    COMPLIANCE, SPEECH, VIDEO_META
)

# Trust level constants
from forge.types import (
    TRUSTED, REPAIRED, QUARANTINED, REJECTED
)

# Version
from forge import __version__  # "2.0.0"