agent-generator

Describe an AI system in one sentence — get a controlled, validated, production-ready project.

A deterministic generation engine with two jobs: scaffold runnable multi-agent projects (CrewAI · LangGraph · WatsonX Orchestrate · CrewAI Flow · ReAct), and power Matrix Builder — give AI coders a contract, not a prompt.

Why agent-generator

One package, two engines that share a deterministic core (one LLM call to plan, everything else template-rendered, so the same input yields byte-identical output):

The Matrix engine is the deterministic core behind Matrix Builder. It enforces the signed Ruslan Magana Definitions, works with Claude Code, Codex, Cursor, GitPilot, IBM Bob (and any AI coder), and publishes validated, signed bundles to MatrixHub.

How it works

1 · Generate a multi-agent project — one LLM call plans; everything else is deterministic template rendering, so the same sentence yields byte-identical, safety-scanned code.

2 · Control an AI coder with mb — AI coders are powerful but out of control: left to a raw prompt they edit any file, invent their own architecture, drift between runs, and produce output you can't verify. That is why Matrix Builder exists. mb gives the AI coder a contract — a locked blueprint, scoped batches, allowed-file boundaries, and fail-closed validation — and records every accepted change as an immutable, versioned Matrix Commit. Batches stack into a complete project, end to end, fully under contract.

Install

pip install agent-generator            # the CLI + the engine + the mb CLI
pip install "agent-generator[openai]"  # + OpenAI provider
pip install "agent-generator[all]"     # + all providers and frameworks

Python 3.10+. No credentials or network are needed for controlled generation and validation — the engine is deterministic.

Quick start

A · Generate a multi-agent project

# pick a provider (WatsonX is the default; OpenAI shown here)
export OPENAI_API_KEY=sk-...; export AGENTGEN_PROVIDER=openai

agent-generator "Research team that finds papers and writes summaries" -f crewai -o team/
cd team && crewai run

# no credentials? generate deterministically with --dry-run
agent-generator "Hello world agent" -f crewai --dry-run

B · Control an AI coder (the Matrix engine)

from agent_generator import AgentGenerator
from agent_generator.contracts import IdeaRequest

engine = AgentGenerator()                                   # deterministic, no credentials
idea   = IdeaRequest(idea="An AI app that analyzes GitHub repositories")

candidates = engine.generate_blueprint_candidates(idea)     # 3 quality-tiered options
blueprint  = engine.generate_controlled_blueprint(idea)     # the locked contract
engine.export_zip(blueprint, "dist/app.zip", release_evidence=True)   # signed bundle

# after your AI coder runs, validate its output against the contract:
report = engine.validate_ai_coder_patch("b1", repo_path="dist/out", blueprint=blueprint)
print(report.status)         # approved | needs-repair | rejected
print(report.repair_prompt)  # bounded fix instructions when not approved

Or from the CLI / HTTP:

agent-generator matrix candidates --idea "An AI app that analyzes GitHub repositories"
agent-generator matrix export     --idea "..." --out dist/app.zip --release-evidence
agent-generator matrix validate   --idea "..." --repo dist/app        # exit 0/1/2

uvicorn agent_generator.http.app:app   # OpenAPI at /openapi.json, routes under /api/v1

The mb CLI — local-first

mb is the local-first Matrix Builder: the full git-for-AI loop on your machine — offline, deterministic, zero infrastructure. State lives in a .mb/ folder that mirrors the server model.

mb init "A GitHub repo intelligence agent" --quality standard   # idea → controlled blueprint
mb next "Add repo ingestion"                                    # plan a scoped batch
mb prompt --coder claude-code                                   # contract-bound prompt (+ CLAUDE.md)
mb check backend/app/...                                        # validate → an immutable Matrix Commit
mb timeline                                                     # the build history
mb repair                                                       # scoped fix prompt from the last failure
mb login && mb sync                                             # push/pull to the cloud (optional)
mb mcp                                                          # expose the build loop as MCP tools

mb check is fail-closed (exit 0 approved · 1 needs-repair · 2 rejected). A passing check creates an immutable Matrix Commit carrying the prompt snapshot, standards lock, file manifest, diff, and validation result. Full guide: docs/matrix-engine/mb-cli.md.

Why it is safe to ship

Frameworks & built-in tools

Built-in tools available to generated agents: web_search, pdf_reader, http_client, sql_query, file_writer, vector_search. Runs on WatsonX by default, OpenAI with one flag, or local models via Ollama / OllaBridge.

Key CLI flags: -f <framework> · -o <path> · --dry-run (no LLM) · -p openai · --show-cost · --mcp.

The platform (web · desktop · mobile)

The same engine ships as a full product — a FastAPI backend, a Vite SPA, Tauri desktop installers, and a Capacitor Android app, from one TypeScript codebase.

make install      # CLI + backend (FastAPI) + frontend (Vite SPA)
make start        # backend :8000 + SPA :5173  (Ctrl-C stops both)
make build        # SPA bundle + backend Docker image + desktop installer for this host

Open http://localhost:5173. Signed CI builds (Authenticode, Apple notarization, GPG, Play Store) live in .github/workflows/; the Kubernetes deployment is in deploy/helm/. A quick visual wizard is also available standalone: uvicorn agent_generator.wsgi:app --port 8000.

Architecture & ecosystem

matrix-builder      orchestration + UX (the public product)
agent-generator     generation + validation        ← this repo (the engine)
matrix-definitions  signed rules / standards (RMD)
MatrixHub           registry for trusted artifacts

• Engine API is versioned (ENGINE_API_VERSION) and contracts are versioned (CONTRACTS_VERSION); the SDK method surface is guarded by parity tests.
• Package 0.2.0 satisfies the matrix-definitions compatibility gate (compatibility.agent_generator >= 0.2.0) — it can load and verify a signed standards pack.

See docs/matrix-engine/compatibility-matrix.md.

Security & supply chain

• Determinism — generation/validation need no network or credentials; identical input → identical output.
• Signed standards — rules come from the signed matrix-definitions pack, checksum-verified at load.
• Release evidence — --release-evidence bundles ship checksums.txt, a CycloneDX SBOM, and a cosign bundle.
• Pinned CI — GitHub Actions pinned to SHAs, least-privilege tokens, CODEOWNERS on workflows/release.

Verify a bundle:

cd dist/out && sha256sum -c artifacts/checksums.txt

Documentation

Full docs (MkDocs) live in docs/. Highlights:

• Get started — Install · Usage · Pick a framework
• Matrix engine — Quickstart · mb CLI · Public engine API · HTTP API · Validation & repair · Ruslan Magana Definitions
• Operations — Platform · Production readiness · Release process

Build the docs site locally: mkdocs serve.

Contributing

git clone https://github.com/ruslanmv/agent-generator.git && cd agent-generator
make install      # CLI + backend + frontend
make test         # CLI pytest + backend pytest + frontend type-check & build
make lint         # ruff + black + isort

Issues and pull requests are welcome. Please run make lint and make test before opening a PR.

License & author

Licensed under Apache 2.0 — see LICENSE.

Created and maintained by Ruslan Magana Vsevolodovna, author of the Ruslan Magana Definitions — the signed standard that keeps AI-built software under contract.