flowchart LR
    subgraph Clients["Clients"]
        A1["🤖 AI Agent"]
        A2["🖥️ Claude Desktop"]
        A3["⚡ Cursor / IDE"]
        A4["🌐 REST API"]
    end

    subgraph Gateway["ToolForge Gateway"]
        direction TB
        B["🔑 Auth Layer\nAPI Key · JWT"]
        C["🛡️ RBAC Engine\nRoles · Capabilities"]
        D["⏱️ Rate Limiter\nSliding Window"]
        B --> C --> D
    end

    subgraph Runtime["Execution Runtime"]
        direction TB
        E["📋 Input Validation\nJSON Schema · Pydantic"]
        F["🔒 Sandbox\nDocker · Subprocess"]
        G["🔄 Retry + Timeout\nExponential Backoff"]
        H["📦 ToolResult\nID · Latency · Error"]
        E --> F --> G --> H
    end

    subgraph Registry["Tool Registry"]
        direction TB
        I["📚 26 Standard Tools\nSemver · Categories"]
        J["🔎 Semantic Search\nFull-Text + Category"]
        I --- J
    end

    subgraph Infra["Infrastructure"]
        K[("🐘 PostgreSQL\nAudit Logs")]
        L[("⚡ Redis\nRate Limits · Cache")]
        M["📈 Prometheus\n/metrics exporter"]
    end

    Clients --> Gateway
    Gateway --> Runtime
    Runtime --> Registry
    Runtime --> Infra

git clone https://github.com/your-username/toolforge
cd toolforge
pip install -e .

import asyncio
from toolforge import ToolForge

tf = ToolForge()

@tf.tool(
    name="calculate_tax",
    description="Calculate income tax for a given gross income and rate.",
    version="1.0.0",
    category="finance",
)
def calculate_tax(income: float, rate: float = 0.2) -> float:
    return income * rate

async def main():
    result = await tf.execute("calculate_tax", {"income": 120_000.0, "rate": 0.28})
    print(result.status.value)       # 'success'
    print(f"${result.result:,.2f}")  # '$33,600.00'
    print(result.execution_id)       # UUID for tracing

asyncio.run(main())

from toolforge import ToolForge
tf = ToolForge.with_standard_tools()

from toolforge import tool, RetryPolicy, StandardCapability

@tool(
    name="fetch_stock_price",
    description="Fetch live stock price from market API.",
    version="1.0.0",
    category="finance",
    capabilities=[StandardCapability.NETWORK.value],
    timeout=10.0,
    retry_policy=RetryPolicy(max_retries=3, initial_delay_sec=0.5),
)
async def fetch_stock_price(ticker: str) -> dict:
    """Fetch stock data for given ticker symbol."""
    return {"ticker": ticker, "price": 185.42}

result = await tf.execute("web_search", {"query": "python asyncio"})

result.execution_id   # UUID — for distributed tracing
result.tool_name      # "web_search"
result.tool_version   # "1.0.0"
result.status         # SUCCESS | FAILED | TIMEOUT | PERMISSION_DENIED
result.result         # structured output
result.error          # ToolErrorInfo(code, message, retryable)
result.duration_ms    # wall-clock latency
result.retry_count    # retries attempted before success
result.unwrap()       # raises RuntimeError on failure, else returns result

from toolforge import PermissionContext

ctx = PermissionContext(
    caller_id="research_agent",
    granted_capabilities={"network", "filesystem_read"},
)

# ✅ Tool requires 'network' — succeeds
result = await tf.execute("web_search", {"query": "AI"}, context=ctx)

# ❌ Tool requires 'code_execution' — returns PERMISSION_DENIED, never raises
result = await tf.execute("python_execute", {"code": "..."}, context=ctx)
print(result.status.value)  # 'permission_denied'

import asyncio
from toolforge import ToolForge

tf = ToolForge.with_standard_tools()
mcp = tf.create_mcp_server(server_name="my-toolforge")
asyncio.run(mcp.run_stdio())

python -m toolforge.integrations.mcp

# POST /mcp — JSON-RPC 2.0
curl -X POST http://localhost:8000/mcp \
  -H "X-API-Key: tf-..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools = tf.to_langgraph_tools()  # List[LangGraphToolWrapper]
# graph = create_react_agent(llm, tools)

openai_tools = tf.to_openai_tools(category="web")
# → [{"type": "function", "function": {"name": ..., "parameters": {...}}}]

from toolforge import parse_openai_tool_call
tool_name, args = parse_openai_tool_call(tool_call_obj)
result = await tf.execute(tool_name, args)

from toolforge import SecuredToolForge, Role, RateLimitConfig

tf = SecuredToolForge.with_standard_tools(
    rate_limit_config=RateLimitConfig(requests_per_minute=60),
    circuit_failure_threshold=5,
    circuit_recovery_timeout_sec=30.0,
)

# Issue scoped API keys per role
dev_key  = tf.api_keys.issue_key(user_id="alice", role=Role.DEVELOPER)
agent_key = tf.api_keys.issue_key(user_id="bob",  role=Role.AGENT)

# Execute with key-based auth and RBAC enforcement
result = await tf.execute("python_execute", {"code": "print('hello')"}, api_key=dev_key)

# Query auto-redacted audit events
events = tf.audit.get_events(caller_id="alice")

uvicorn toolforge.server:app --host 0.0.0.0 --port 8000 --workers 4

python examples/repo_debugger_agent.py

Step 1  discover   →  directory_list + file_search     find project structure
Step 2  reproduce  →  python_execute                   run failing tests
Step 3  inspect    →  file_read                        read buggy source
Step 4  patch      →  file_write                       apply autonomous fix
Step 5  verify     →  python_execute                   re-run tests → green
Step 6  report     →  structured summary               root cause + timing

[REPORT] AGENT RESOLUTION SUMMARY
  Total Steps:   6
  Total Runtime: 249.6ms
  Root Cause:    Unhandled division by zero in calculator.py
  Resolution:    Patched divide() with explicit ValueError guard
  Final Status:  RESOLVED

docker compose up --build

Lint (ruff)  →  Test Matrix (3 OS × 3 Python)  →  Agent Smoke Test  →  Docker Build

# Run all 86 tests (unit, integration, API, agent)
python -m pytest tests/ -v

86 passed in 6.89s