Metadata-Version: 2.4
Name: intentspec
Version: 0.1.0
Summary: Local-first task contract compiler for AI systems.
Author-email: Ting Liu <research@symboliclight.com>
License-Expression: MIT
Keywords: agent,contracts,llm,software-engineering,structured-output
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: jsonschema<5.0,>=4.23
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: mypy<2.0,>=1.10; extra == "dev"
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: pytest-cov<6.0,>=5.0; extra == "dev"
Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
Requires-Dist: twine<7.0,>=6.0; extra == "dev"
Requires-Dist: types-PyYAML<7.0,>=6.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/intentspec-logo.svg" alt="IntentSpec logo" width="720">
</p>

# IntentSpec

**Contracts for AI agent tasks.**

IntentSpec is a local-first offline contract compiler for AI agent tasks.

It lets a team maintain one `intent.yaml` contract and compile it into artifacts
that existing tools can read, including `AGENTS.md`, `CLAUDE.md`, Cursor Rules,
OpenAI Structured Outputs, Gemini structured output payloads, and MCP-oriented plan
artifacts.

```text
intent.yaml
  -> validate
  -> resolve imports
  -> inspect normalized IIR
  -> compile to target artifacts
  -> run your agent
  -> test the output offline
```

> Turn scattered AI agent instructions into versioned, compilable, testable
> contracts.

IntentSpec does not call real LLM APIs, does not require API keys, and does not
replace an agent runtime. It does three things:

- records task goals, permissions, constraints, human gates, output formats, and
  acceptance tests as a structured contract;
- compiles that contract into tool-specific artifacts;
- tests final agent outputs with deterministic offline checks.

For a longer walkthrough, see [docs/technical-guide.md](docs/technical-guide.md).

## Why It Matters

AI agent instructions are often scattered across prompts, repository rules,
structured output schemas, and tool-specific memory files. That makes them hard to
review, migrate, reuse, or test.

IntentSpec adds a small contract layer before those artifacts:

- write the task once as a structured contract;
- compile it into the formats your tools already read;
- test the final output locally before accepting it.

No model calls. No API keys. No new runtime to adopt.

## Five-Minute Tryout

```bash
pip install -e ".[dev]"
intent validate examples/code_review.intent.yaml
intent inspect examples/code_review.intent.yaml
intent compile examples/code_review.intent.yaml --target agents-md --out AGENTS.md
intent test examples/customer_brief.intent.yaml examples/customer_brief.output.md
```

## Who It Is For

IntentSpec is useful for engineering teams that use multiple AI coding tools and do
not want to maintain the same rules in several formats. It is also useful for AI
application developers who need stable JSON outputs, governance reviewers who want
permissions and confirmation gates to be explicit, and researchers studying
artifact-level agent governance.

The generated files are IntentSpec artifacts that can be reviewed, committed, and
used by downstream tools.

IntentSpec is not:

- an LLM runtime;
- an agent orchestration framework;
- a permission sandbox;
- a runtime enforcement system;
- an MCP replacement;
- a replacement for Cursor, Codex, Claude Code, or other tools.

It helps express, propagate, migrate, and check rules. It cannot guarantee that a
downstream model will obey an instruction at runtime.

## What You Get

Using IntentSpec gives a project:

- a code-reviewable AI task contract;
- generated artifacts for multiple downstream tools;
- reusable governance packs through `IntentPack`;
- explicit permission boundaries and human confirmation gates;
- local or CI-friendly output acceptance tests;
- a migration path from existing instruction files back into structured contracts;
- visibility into target capability limits.

## Install

Python 3.11 or newer is required.

Install from PyPI after publication:

```bash
pip install intentspec
```

Install from source:

```bash
git clone https://github.com/<your-org>/IntentSpec.git
cd IntentSpec
pip install -e ".[dev]"
```

Check the CLI:

```bash
intent --help
```

IntentSpec core workflows do not need API keys or network access.

## Minimal Contract

```yaml
version: "0.1"
kind: "IntentSpec"
metadata:
  name: "code_review"
  title: "Review code changes"
  owner: "engineering"
task:
  goal: "Review the repository and report correctness, security, and maintainability issues."
  audience:
    - "maintainers"
permissions:
  web: false
  filesystem:
    read: true
    write: false
  network: false
  tools:
    send_email: false
    read_calendar: false
    read_gmail: false
    create_file: false
    delete_file: false
    purchase: false
constraints:
  - "Do not modify files."
  - "Do not expose secrets."
output:
  format: "markdown"
  sections:
    - "Summary"
    - "Findings"
    - "Risks"
    - "Tests"
tests:
  - name: "Must include required sections"
    assert:
      - type: "required_sections"
```

Save this as `code_review.intent.yaml`.

## Common Commands

Validate a contract:

```bash
intent validate examples/code_review.intent.yaml
```

Inspect the normalized intermediate representation:

```bash
intent inspect examples/code_review.intent.yaml
```

Compile an artifact:

```bash
intent compile examples/code_review.intent.yaml --target agents-md --out AGENTS.md
```

Test an output:

```bash
intent test examples/customer_brief.intent.yaml examples/customer_brief.output.md
```

Import an existing artifact:

```bash
intent import AGENTS.md --type agents-md --out imported.intent.yaml
```

Generate the JSON Schema:

```bash
intent schema --out schema/intentspec.schema.json
```

## Targets

IntentSpec currently supports these compile targets:

| Target | Use |
| --- | --- |
| `agents-md` | Repository instruction files such as `AGENTS.md` |
| `claude-md` | Claude-style project memory |
| `cursor-rules` | Cursor Project Rules |
| `antigravity-rules` | Antigravity-compatible repository rules |
| `openai-structured` | JSON schema based structured outputs |
| `gemini-structured` | Gemini structured output payloads |
| `mcp-plan` | MCP-oriented plan artifacts |

See [docs/integrations.md](docs/integrations.md) for integration details.

## IntentPack

Reusable governance fields can be stored in an `IntentPack`.

```yaml
version: "0.1"
kind: "IntentPack"
metadata:
  name: "privacy_pack"
  title: "Privacy constraints"
permissions:
  web: false
  network: false
constraints:
  - "Do not expose personal data."
  - "Mask secrets before quoting evidence."
tests:
  - name: "Must avoid secret markers"
    assert:
      - type: "no_regex"
        pattern: "(?i)(api[_-]?key|secret|password)"
```

Contracts can import packs and resolve them before validation, compilation, or
testing.

## Python API

```python
from intentspec_core import (
    inspect_document,
    load_document,
    resolve_document_imports,
    validate_document,
)

document = load_document("examples/code_review.intent.yaml")
resolved = resolve_document_imports(document)
report = validate_document(resolved)
iir = inspect_document(resolved)
```

If you only handle full `IntentSpec` contracts, you can also use narrower helpers
such as `load_spec`, `resolve_imports`, and `validate_spec`.

## Repository Layout

```text
packages/intentspec-core/   schema, parser, IIR, imports, targets, testing
packages/intentspec-cli/    Typer CLI and intent command
packages/intentspec-mcp/    thin MCP server
packages/intentspec-ts/     TypeScript package MVP
packages/intentspec-vscode/ VS Code extension MVP
examples/                   runnable example contracts and outputs
schema/                     generated JSON Schema
benchmark/                  offline benchmark and reproducible benchmark artifacts
docs/                       technical docs, migration guide, and Chinese docs
tests/                      pytest test suite
```

## Documentation

- [docs/technical-guide.md](docs/technical-guide.md)
- [docs/integrations.md](docs/integrations.md)
- [docs/iir.md](docs/iir.md)
- [docs/migration-v0.1.md](docs/migration-v0.1.md)
- [docs/zh/README.md](docs/zh/README.md) for Simplified Chinese documentation
- [benchmark.md](benchmark.md)
- [failure-cases.md](failure-cases.md)

## Benchmark

Run the basic benchmark:

```bash
python benchmark/run_benchmark.py
```

Run the reproducible benchmark:

```bash
python benchmark/reproducible_artifact/scripts/run_all.py
```

The benchmark does not call real LLM APIs. It evaluates local artifacts, compile
behavior, round-trip import, and deterministic tests.

Current reproducible benchmark snapshot:

| Metric | Result |
| --- | ---: |
| Contracts | 20 |
| Compile matrix | 94 / 120 successful target compilations |
| Compiled round-trip imports | 74 / 100 successful imports |
| Handwritten artifact imports | 20 / 20 successful imports |
| Valid output pass rate | 19 / 20 |
| Targeted defect catch rate | 32 / 32 |

Detailed generated results live in
[benchmark/reproducible_artifact/results](benchmark/reproducible_artifact/results).

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
mypy
```

Build the release package:

```bash
python -m build
twine check dist/*
```

The first public package intentionally focuses on technical documentation,
user guides, API/CLI usage, examples, tests, and reproducible benchmark assets.

## Roadmap

Planned directions include better draft generation, richer assertion selection,
more round-trip fidelity tests, clearer target capability diagnostics, pack
registries, import traces, workflow-level contract composition, IDE diagnostics,
and optional model-based semantic evaluation.

## License

MIT. See [LICENSE](LICENSE).
