xAI-Forge

xAI-Forge is a deterministic agent runtime, trace store, and UI for building reproducible AI runs. It ships with a typed Python SDK, plugin hooks, trace exporters, and a local-first workflow that keeps everything auditable.

Why xAI-Forge exists: teams need a way to capture, replay, and explain agent behavior without relying on paid services. xAI-Forge makes trace integrity a first-class feature.

Disclaimer: This is an independent project inspired by frontier AI tooling needs and is not affiliated with or endorsed by xAI (the company). Disclaimer: The project name is aspirational and does not indicate any official tooling.

Install

Runtime (CLI + API)

python -m venv .venv
source .venv/bin/activate
pip install -e .

Python SDK

pip install -e ".[sdk]"

Quickstarts

CLI

python -m xaiforge run --task "Solve 23*47 and show your steps"
python -m xaiforge export latest --format markdown
python -m xaiforge query "type=tool_call AND tool~search"

Python SDK

from xaiforge_sdk import Client

client = Client("http://127.0.0.1:8000")
for event in client.start_run("Summarize the repo"):
    print(event.type, event.ts)

UI

python -m xaiforge serve
cd web
npm install
npm run dev

Open:

• API: http://localhost:8000
• UI: http://localhost:5173

Architecture

graph TD
  CLI[CLI + SDK] --> API[FastAPI server]
  API --> Runner[Agent runner]
  Runner --> TraceStore[.xaiforge/traces]
  TraceStore --> UI[Web UI]
  TraceStore --> Exporters[Exporters]
  TraceStore --> Plugins[Plugins]

Loading

See ARCHITECTURE.md for the full data flow.

Security model

xAI-Forge keeps all traces on disk by default, supports redaction plugins, and is offline-first. Read more in docs/SECURITY.md.

Reproducibility

• Deterministic traces are hashed (rolling SHA-256).
• python -m xaiforge replay <trace_id> replays and verifies integrity.
• scripts/gen_sample_traces.py seeds example traces.
• web/scripts/capture_screenshots.ts regenerates UI screenshots using Playwright.

Documentation

• Features
• SDK
• Runtime design
• Event spec
• Security model
• Providers
• Tools
• Roadmap

License

Apache-2.0

60-second Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m xaiforge run --task "Solve 23*47 and show your steps"

Demo

Run the recruiter-ready demo (policy + metrics enabled):

./scripts/demo.sh

Verification

./scripts/verify.sh

What's new

• Forge Model Gateway: provider-agnostic requests, streaming, batching, and retry controls.
• Forge Evals + Regression: JSONL datasets, scorers, and CI gate for score drift.
• Forge Safety Layer: PII + secret scrubbing with policy enforcement.
• Trace Replay + Diff: deterministic verification and run-to-run drift reports.

Features

• Deterministic trace store with Markdown/HTML/JSON exports.
• Optional policy guardrails for tool calls (XAIFORGE_POLICY_FILE).
• Optional structured logging + in-process metrics (XAIFORGE_ENABLE_LOGGING=1, XAIFORGE_ENABLE_METRICS=1).
• Bench reports under .xaiforge/bench/latest.md after each run.

Project structure

• xaiforge/ — runtime, providers, tools, plugins, observability, policy.
• xaiforge_sdk/ — typed Python SDK.
• web/ — React UI.
• scripts/ — verify, demo, doctor, and release utilities.
• tests/ — unit + integration tests.

Design decisions

• Offline-first by default (network requires --allow-net).
• Append-only JSONL event streams with rolling hashes for integrity.
• Optional guardrails are opt-in to preserve existing defaults.