Metadata-Version: 2.4
Name: specular-ai
Version: 0.2.0
Summary: Spec-as-Source Framework: AI-driven development where specifications are the source of truth.
Project-URL: Homepage, https://github.com/symbolfarm/specular
Project-URL: Repository, https://github.com/symbolfarm/specular
Project-URL: Issues, https://github.com/symbolfarm/specular/issues
Author-email: Toby Lightheart <code@symbolfarm.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,code-generation,llm,mcp,specifications
Classifier: Development Status :: 3 - Alpha
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: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Requires-Dist: mcp>=0.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.0.0; extra == 'dev'
Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Specular

**Specular** is a "Spec-as-Source" AI coding framework. It treats rigorous, SRS-style specifications as the source of truth and uses LLMs to compile them into executable code.

## Key Features

-   **Spec-as-Source**: Code is a build artifact. You edit the Spec, not the Python/JS file.
-   **Contracts over Code**: Define *what* you want (Functional Requirements) and *constraints* (Non-Functional Requirements).
-   **Self-Healing**: An autonomous loop (`attempt_fix`) analyzes test failures and patches code to resolve discrepancies.
-   **Multi-Provider**: Supports Google Gemini and Anthropic Claude via a pluggable provider system.
-   **Agent-Native**: Also available as an MCP server for AI agents.

## Installation

```bash
pip install specular-ai
```

Or for development:
```bash
git clone https://github.com/symbolfarm/specular.git
cd specular
uv sync
```

## Quick Start

```bash
# Set your API key
export GEMINI_API_KEY="your-key-here"

# Create a new spec
specular create calculator "A simple calculator with add and multiply"

# Edit src/calculator.spec.md to define your requirements...

# Compile to code
specular compile calculator

# Run the generated tests
specular test calculator

# If tests fail, auto-fix
specular fix calculator
```

## The Workflow

Specular isn't just a code generator; it's an architecture tool.

1.  **Architecture First**: Define your data types (`types.spec.md`) before your logic.
2.  **Leaves-Up Strategy**: Build dependencies (utils, helpers) before the core business logic.
3.  **The Loop**:
    *   **Edit Spec** -> `specular compile` -> `specular test`.
    *   **Failure?** -> `specular fix` (Let the AI patch the code).
    *   **Ambiguity?** -> Refine the Spec (don't touch the code).

## CLI Reference

```
specular list                     List all specs in src/
specular create <name> <desc>     Create a new spec from template
specular validate <name>          Check spec structure
specular compile <name>           Compile spec to code + tests
specular test <name>              Run tests for a spec
specular fix <name>               Auto-fix failing tests
specular build                    Compile all specs in dependency order
  --incremental                   Only recompile changed specs
  --parallel                      Compile independent specs concurrently
```

## LLM Providers

**Google Gemini (default)**
```bash
export GEMINI_API_KEY="your-key-here"
export SPECULAR_LLM_MODEL="gemini-2.0-flash"  # optional
```

**Anthropic Claude**
```bash
export SPECULAR_LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="your-key-here"
export SPECULAR_LLM_MODEL="claude-sonnet-4-20250514"  # optional
```

## MCP Server (for AI Agents)

Specular can run as an MCP server for Claude Desktop or other AI agents:

```json
"specular": {
  "command": "uv",
  "args": ["run", "specular-mcp"],
  "env": {
    "GEMINI_API_KEY": "your-key-here"
  }
}
```

Or use the CLI: `specular mcp`

## Development

```bash
uv run pytest    # Run tests
uv run ruff check src/  # Lint
```
