intract 0.5.9

Intent contract tagging, validation and semantic mapping for codebases.

Intract

AI Cost Tracking

• 🤖 LLM usage: $2.5558 (14 commits)
• 👤 Human dev: ~$749 (7.5h @ $100/h, 30min dedup)

Generated on 2026-06-01 using openrouter/qwen/qwen3-coder-next

---

Intract is an intent-contract layer for codebases and software delivery artifacts.

It lets you describe, validate and monitor intent across:

code
functions
classes
files
project manifests
API endpoints
Dockerfiles
CI/CD workflows
Kubernetes manifests
DevOps artifacts

Intract is not primarily a programming language. It is a contract system for short, portable intent declarations.

Quick example

# @intract.v1 scope:function intent:validate:user_permission priority:1 domain:security input:user,resource output:allowed effect:none forbid:write,network validate:input_presence,return_value,no_forbidden_effect meaning:"check whether user can modify resource without changing state"
def can_update_resource(user, resource):
    return user.is_admin or resource.owner_id == user.id

Run:

python -m intract scan .
python -m intract validate .

External Target Addressing (Toon Manifests)

In addition to inline annotations, Intract supports two ways of defining quality gates and intent contracts:

1. Inline Comments: Using @intract.v1 in source files.
2. External manifests (Toon Manifests): Decoupled files (.toon or intract.toon.yaml) that specify precise coordinates (targets) for files, functions, lines, and XPaths.

1. Płaski format URI linia po linii (.toon)

Pliki .toon używają struktury URI do prostego i przejrzystego przypisywania kontraktów na poziomie konkretnych linii, funkcji lub selektorów:

# Flat target-based URI rules
intract://src/calc.py?func=add#id=pure-addition&intent=pure-add&forbid=write
intract://src/calc.py?func=write_to_log&line=13#id=log-write&intent=write-log&require=write

2. Manifest YAML z targetowaniem (intract.toon.yaml)

Możesz również zdefiniować zasady w formacie YAML, podając sekcję target:

version: intract.v1
contracts:
  - id: addition-check
    intent: pure:addition
    forbid: [write]
    target:
      file: src/calc.py
      function: add

Więcej informacji i pełne przykłady znajdziesz w katalogu examples/toon/.

Documentation

Start here:

• Docs index
• Getting Started
• Commands Reference
• Contract Format
• Manifest intract.yaml
• Architecture
• Validation Model
• Watch & Engine
• Plugins
• Integrations
• Roadmap

Important project locations

Core:

• src/intract/
• src/intract/models.py
• src/intract/parser.py
• src/intract/signature.py
• src/intract/validation.py

Operational modules:

• src/intract/cli.py
• src/intract/config.py
• src/intract/policy.py
• src/intract/git.py
• src/intract/watch.py

Analysis engine:

• src/intract/engine/
• src/intract/engine/scanner.py
• src/intract/engine/analyzer.py
• src/intract/engine/assigner.py
• src/intract/engine/drift.py
• src/intract/engine/monitor.py

Plugins and integrations:

• src/intract/plugins/
• src/intract/integrations/
• src/intract/integrations/planfile.py
• src/intract/artifacts.py
• src/intract/reporters/sarif.py

Schemas and templates:

• schemas/intract.schema.json
• templates/
• templates/intract.yaml
• templates/pyproject-intract.toml
• templates/openapi.intract.yaml
• templates/Dockerfile.intract

Examples:

• examples/README.md — indeks wszystkich przykładów
• examples/web-app/ — aplikacja webowa: iteracje v1/v2 + mock UI
• examples/full-stack/ — graf, duplikaty intencji
• examples/integration_tests/

SDKs:

• sdks/python/
• sdks/typescript/
• sdks/go/
• sdks/rust/
• sdks/java/
• sdks/csharp/

CI / packaging:

• .pre-commit-hooks.yaml
• .github/workflows/intract.yml
• Dockerfile
• pyproject.toml

Installation

pip install -e .[dev]

Main commands

python -m intract scan .
python -m intract validate .
python -m intract check .
python -m intract check --staged
python -m intract check --changed --base main
python -m intract check . --format sarif --output intract.sarif
python -m intract check-manifest intract.yaml
python -m intract coverage .
python -m intract duplicates .
python -m intract graph . --format mermaid
python -m intract watch .
python -m intract tickets .
python -m intract artifact Dockerfile
python -m intract artifact openapi.yaml
python -m intract engine suggest .
python -m intract engine drift .
python -m intract engine run .

Run examples

python examples/integration_tests/run_examples.py

Expected:

example_01: pass
example_02: violation + planfile-compatible ticket
example_03: watch/engine/drift works

Project manifest

Generate:

python -m intract init .

Validate:

python -m intract check-manifest intract.yaml
python -m intract validate . --manifest intract.yaml

Pre-commit

Example .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: intract
        name: intract intent contracts
        entry: intract check --staged
        language: system
        pass_filenames: false

SARIF / GitHub Code Scanning

python -m intract check . --format sarif --output intract.sarif

GitHub workflow:

• .github/workflows/intract.yml

License

Licensed under Apache-2.0.