autocraft 0.1.0

AutoCraft Enterprise — AST-Safe, Git-Native LLM code generation for FastAPI projects.

AutoCraft Enterprise

LLM-powered, AST-safe code generation for FastAPI projects.

Describe an endpoint in plain English. AutoCraft generates the handler, Pydantic schemas, and pytest suite — validated, linted, and committed to a dedicated Git branch. Ready to review.

---

Why AutoCraft?

Without AutoCraft	With AutoCraft
Write async handler with type hints	Generated automatically, matching your project conventions
Define Pydantic v2 request/response schemas	Inferred from your description and existing models
Register routes and middlewares	Declared in autocraft.yaml, applied automatically
Write tests (happy path + edge cases)	Generated as a full pytest-asyncio suite
Open API docs and docstrings	Inserted automatically with Args/Returns/Raises

AutoCraft is not a chat assistant. It is a deterministic generation pipeline: the LLM's output is always AST-validated, ruff-fixed, and Git-branched for human review before touching your codebase.

---

Installation

pip install autocraft

Requires Python 3.11+.

---

Quick Start

# 1 — Set your API key
export MISTRAL_API_KEY=sk-...          # or add to .env

# 2 — Initialise AutoCraft in your project
cd my-fastapi-project
autocraft init                          # creates autocraft.yaml

# 3 — Generate an endpoint
autocraft generate "POST /orders that receives customer_id, product_ids and quantities,
                    validates stock, saves to DB, returns the order with total price"

AutoCraft will:

1. Parse your description (Mistral extracts method, path, inputs, rules, side-effects).
2. Scan your project via AST (detects existing models, schemas, conventions).
3. Generate handler + schemas + tests using a senior-grade prompt.
4. Validate via ast.parse → mypy → ruff --fix.
5. Commit to a new branch (autocraft/order-post-<ts>) — ready for git diff.

---

Generated Output

For POST /orders:

app/handlers/order.py       ← async FastAPI route with Depends, HTTPException, docstrings
app/schemas/order.py        ← OrderCreate, OrderResponse (Pydantic v2)
tests/test_order.py         ← pytest-asyncio suite with happy path + edge cases

Sample generated handler:

@router.post("/orders", status_code=status.HTTP_201_CREATED, response_model=OrderResponse)
async def create_order(
    order_data: OrderCreate,
    db: Annotated[AsyncSession, Depends(get_db)],
    current_user: Annotated[User, Depends(get_current_user)],
) -> OrderResponse:
    """
    Create a new order with the given products and quantities.

    Validates stock availability, calculates total price,
    and persists the order and its line items atomically.

    Args:
        order_data: Customer ID, product IDs, and quantities.
        db: Injected async database session.
        current_user: JWT-authenticated user.

    Returns:
        OrderResponse with id, total_price, and created_at.

    Raises:
        HTTPException 400: mismatched list lengths.
        HTTPException 404: unknown customer or product.
        HTTPException 409: insufficient stock.
    """

---

Configuration (autocraft.yaml)

version: '1.0'

llm:
  provider: mistral               # mistral | openai | anthropic | azure
  model: mistral/mistral-large-latest
  temperature: 0.2                # low = consistent code
  max_tokens: 4096

context:
  scan_paths:                     # dirs scanned by the AST analyzer
    - app/handlers
    - app/schemas
    - app/models
    - app/services
  max_examples: 3                 # few-shot examples sent to the LLM

generation:
  output:
    handlers: app/handlers/
    schemas:  app/schemas/
    tests:    tests/
  auto_approve: false             # always show diff before merging
  create_branch: true
  branch_prefix: autocraft/

validation:
  run_mypy: true
  run_ruff: true
  run_tests: true
  min_coverage: 80
  max_retries: 3

---

CLI Reference

Command	Description
autocraft init	Scaffold autocraft.yaml in the current directory
autocraft generate "<description>"	Run the full generation pipeline
autocraft review	Inspect or approve the last generated diff

---

How It Works

Natural Language Description
        │
        ▼
┌───────────────────┐
│  Intent Parser    │  Mistral extracts: method, path, handler_name,
│  (LLM Phase 1)   │  inputs+types, business rules, side-effects, auth
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Context Analyzer │  AST scans project → detects Pydantic models,
│  (AST)           │  ORM entities, function signatures, decorators
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Code Generator   │  Senior-grade mega-prompt → Mistral produces
│  (LLM Phase 2)   │  handler + schemas + tests as a JSON bundle
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Validation       │  ast.parse (hard gate) → mypy → ruff advisory
│  Pipeline        │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Review Gateway   │  ruff --fix auto-repair → write to disk
│  (Git-Native)    │  → git branch + stage → diff summary
└───────────────────┘

---

Alternative LLM Providers

Edit autocraft.yaml and set the corresponding environment variable:

# OpenAI GPT-4o
llm:
  provider: openai
  model: gpt-4o
# OPENAI_API_KEY=...

# Anthropic Claude
llm:
  provider: anthropic
  model: claude-sonnet-4-6
# ANTHROPIC_API_KEY=...

AutoCraft uses litellm under the hood, so any provider supported by litellm works out of the box.

---

Security

• The LLM never receives credentials, .env files, or production data.
• Generated code is validated in an isolated tempfile.TemporaryDirectory before being written to disk.
• auto_approve: false (default) — every generation requires a human diff review.
• The .env file is in .gitignore and never committed.

---

Contributing

Pull requests are welcome. For major changes, open an issue first.

git clone https://github.com/autocraft-ai/autocraft
cd autocraft
pip install -e ".[dev]"
pytest

---

License

MIT © 2026 AutoCraft Contributors