Metadata-Version: 2.4
Name: af-toolkit
Version: 0.1.0
Summary: Fast AF developer tooling for AI agents
License: MIT
License-File: LICENSE
Keywords: mcp,agent,llm,ai,openapi,ast,eval,fastmcp,context-window
Author: Andrea Pallotta
Author-email: andreapallotta.dev@gmail.com
Requires-Python: >=3.10
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: all
Provides-Extra: audit
Provides-Extra: forge
Provides-Extra: slice
Provides-Extra: studio
Requires-Dist: cryptography (>=42.0)
Requires-Dist: httpx (>=0.27)
Requires-Dist: oauthlib (>=3.2)
Requires-Dist: pydantic (>=2.0)
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: rich (>=13.0) ; extra == "audit" or extra == "all"
Requires-Dist: typer (>=0.12)
Project-URL: documentation, https://github.com/andreapallotta/af-toolkit#readme
Project-URL: homepage, https://andreapallotta.dev
Project-URL: repository, https://github.com/andreapallotta/af-toolkit
Description-Content-Type: text/markdown

<div align="center">
  <img src="assets/logo.jpg" width="220" alt="AgentForge Logo" style="border-radius: 12px; margin-bottom: 12px;" />
  <h1>AgentForge Toolkit (af-toolkit)</h1>
  <p><strong>Fast AF developer tooling for AI agents.</strong></p>
  <p>Build, test, slice, audit, evaluate, and sandbox Model Context Protocol (MCP) servers and agent trajectories.</p>

  <p>
    <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+" /></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
    <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff" /></a>
  </p>
</div>

---

## Key Modules & Capabilities

```text
+-------------------------------------------------------------------------+
|                           AgentForge Toolkit                            |
+-------------------+-------------------+---------------------------------+
| Forge             | Slice             | Audit & Observability           |
| - OpenAPI to MCP  | - AST Skeletons   | - Trajectory Diagrams & Diffs   |
| - Mock Servers    | - Repo Slicer     | - Safety & Policy Scanner (A-F) |
| - Python to MCP   | - Git Diff Slicer | - Benchmark Comparator          |
| - Docker Exporter | - Multi-Model Tok | - Cost Estimator ($)            |
| - Client Exporter | - Prompt Wrappers | - PII Redactor & Failure Diag   |
| - Compliance Test | - JSON & MD Slicer| - Commit Message Generator      |
+-------------------+-------------------+---------------------------------+
| Gateway & REPL    | Eval & Sandbox    | Studio & DX                     |
| - Multi-Server GW | - SWE-bench Eval  | - Interactive Web Workbench     |
| - Stdio Debugger  | - Git Snapshot    | - System Doctor & Initializer   |
| - Polyglot Bridge | - Auto-Rollback   | - Antigravity Skill Exporter    |
| - Interactive REPL| - Resource Bounds | - IDE Agent Rules Exporter      |
+-------------------+-------------------+---------------------------------+
```

---

## Quickstart

### 1. Installation
```bash
pip install af-toolkit
```

### 2. Generate an MCP Server from OpenAPI
```bash
af forge generate api_spec.json -o server.py --service github
```

### 3. Generate Client Configuration
```bash
af forge config server.py --client all
```

### 4. Slice Code & Repositories for LLM Prompts
```bash
af slice-repo ./my_project --budget 6000 -o repomap.md
af tokens ./my_project/main.py
```

### 5. Audit Trajectory Logs
```bash
af audit report trajectory.jsonl -o audit_report.md
af audit safety trajectory.jsonl
af audit cost trajectory.jsonl --model claude-3-5-sonnet
```

### 6. Interactive MCP Debugger & REPL
```bash
af mcp-repl "python server.py"
```

### 7. Run Agent Benchmark Evaluations
```bash
af eval run tasks.jsonl --agent-cmd "agy" -o eval_report.md
```

### 8. Ephemeral Sandbox with Auto-Rollback
```bash
af sandbox run "pytest tests/" --rollback
```

### 9. Launch AgentForge Studio
```bash
af studio --port 8000
```

---

## CLI Command Reference

| Command | Description |
|---|---|
| `af forge generate <spec>` | Generate FastMCP server from OpenAPI 3.0/3.1 or Swagger 2.0. |
| `af forge mock <spec>` | Generate offline mock MCP server with synthetic responses. |
| `af forge python <source.py>` | Convert Python functions directly into MCP tools. |
| `af forge doc <server.py>` | Generate Markdown documentation tool catalog. |
| `af forge docker <server.py>` | Generate Dockerfile and docker-compose.yml. |
| `af forge config <server.py>` | Export ready-to-use JSON config for Claude Desktop / Cursor / Antigravity. |
| `af test-mcp <server_or_spec>` | Validate MCP schemas, signatures, and docstrings. |
| `af slice <file.py>` | AST code skeletonization under token budgets. |
| `af slice-repo <dir>` | Repository architecture map for system prompts. |
| `af tokens <target>` | Multi-model token calculator across GPT-4o, Claude, Gemini, DeepSeek. |
| `af slice-json <file>` | Prune large JSON/YAML data files. |
| `af slice-md <file>` | Extract Markdown headings and lead sections. |
| `af audit report <log>` | Trajectory metrics, Mermaid sequence diagrams, and git diff snippets. |
| `af audit safety <log>` | Security scan for leaked keys, destructive commands, loop storms. |
| `af audit compare <l1> <l2>` | Side-by-side benchmark comparison between agent runs. |
| `af audit cost <log>` | Calculate dollar cost ($) across LLM models. |
| `af audit redact <log>` | Sanitize PII, credentials, and IPs in trajectory logs. |
| `af audit diagnose <log>` | Cluster tool errors and generate parameter suggestions. |
| `af audit commit-msg <log>` | Generate conventional commit message from touched files. |
| `af mcp-repl <server_cmd>` | Interactive stdio terminal REPL for debugging MCP servers. |
| `af gateway --servers <cmds>` | Multi-server MCP multiplexer gateway. |
| `af eval run <tasks.jsonl>` | Run agent evaluation harness and generate scorecards. |
| `af sandbox run <command>` | Execute command inside snapshot-guarded sandbox. |
| `af sandbox snapshot/rollback`| Manage git working directory snapshots. |
| `af export-skill <server.py>` | Export Antigravity skill package (SKILL.md, scripts/, references/). |
| `af export-rules` | Export .cursorrules, .windsurfrules, or AGENTS.md. |
| `af config set/list/path` | Manage credentials in ~/.af/auth.toml. |
| `af config export-env` | Export credentials to .env. |
| `af doctor` | System & environment diagnostics. |
| `af init [--ci]` | Scaffold project and CI/CD workflows. |
| `af studio` | Launch FastAPI web workbench. |

---

## License
MIT License. Created for AI agent developers.

