- 🤖 LLM usage: $3.5862 (18 commits)
- 👤 Human dev: ~$1037 (10.4h @ $100/h, 30min dedup)
Generated on 2026-06-04 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.
# Comment form (all supported languages)
# @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.idDecorator form (same contract model, no comment prefix):
@intract.v1 id:safe-decoder scope:function intent:decode:header domain:security forbid:unsafe
pub fn decode_header(raw_data: &[u8]) -> Header {
// ...
}Rust attributes are also accepted: #[intract.v1 id:safe-decoder intent:decode:header forbid:unsafe].
Run:
python -m intract scan .
python -m intract validate .Poniżej gotowe wzorce użycia, które możesz pokazać zespołowi jako „jak to działa w praktyce”.
Cel: szybko pilnować intencji funkcji i nie spowalniać developmentu.
Przykładowe technologie:
- Python API (
@intract.v1nad funkcjami serwisowymi) - TypeScript frontend (kontrakty
ui.*,validate.*) - Dockerfile (kontrakty deploy, np.
forbid:root_user)
Workflow:
# lokalnie podczas developmentu
python -m intract validate .
python -m intract check --staged --hunks
# szybki podgląd pokrycia i duplikatów intencji
python -m intract coverage .
python -m intract duplicates . --threshold 0.8Cel: rozdzielić intencje na domeny i mieć osobne bramki jakości.
Przykładowe technologie w 1 monorepo:
- Backend: Python + Java + Go
- Frontend: TypeScript
- Platforma: Dockerfile, Kubernetes, GitHub Actions/OpenAPI
Workflow:
# pełna walidacja release branch
python -m intract validate . --manifest intract.yaml
# raport do security/code scanning
python -m intract check . --format sarif --output intract.sarif
# graf zależności intencji i braków require
python -m intract graph . --format mermaidNajpraktyczniej mieć osobne manifesty lub sekcje dla różnych etapów pracy:
intract.dev.yaml→ fokus na poprawność funkcji (domain:app,domain:logic)intract.ci.security.yaml→ fokus na bezpieczeństwo (domain:security,forbid:network/write/unsafe)
Przykład uruchamiania:
# development: sprawdzamy głównie intencje funkcji
python -m intract validate . --manifest intract.dev.yaml
# CI/CD: sprawdzamy głównie bezpieczeństwo i artefakty dostarczeniowe
python -m intract validate . --manifest intract.ci.security.yaml
python -m intract scan . --all-artifacts --jsonW praktyce daje to możliwość „przełączania radaru”:
- dev: czy funkcja robi to, co obiecuje (
intent,input/output,return) - CI/CD: czy release spełnia polityki bezpieczeństwa (network, secrets, root, workflow)
Intract wspiera generowanie kontraktów automatycznie (LLM i engine):
# 1) propozycje kontraktów z konkretnego pliku (LLM)
python -m intract propose llm --file src/auth.py --goal "RBAC without network side effects"
# 2) sugestie engine dla projektu
python -m intract engine suggest .
# 3) walidacja po zaakceptowaniu propozycji
python -m intract validate .Wskazówka: zacznij od małej liczby kontraktów (kluczowe funkcje), potem rozszerzaj obszary.
Poniższy scenariusz pokazuje start od zera dla nowej aplikacji.
mkdir my-app && cd my-app
python -m venv .venv
source .venv/bin/activate
pip install intract
python -m intract init .Przykład celu:
"Zbuduj API do zarządzania zadaniami. Endpoint create-task ma walidować input, nie może robić zewnętrznych wywołań sieciowych i ma zwracać jawny status."
Tworzysz szkic pliku (src/tasks.py) i prosisz Intract/LLM o propozycje:
python -m intract propose llm --file src/tasks.py --goal "task API: validate input, no network, explicit status"Wynik to linie @intract.v1 ..., które możesz wkleić nad funkcje lub przenieść do manifestu Toon/YAML.
Implementujesz funkcje zgodnie z intencją, np.:
intent:create:taskforbid:networkvalidate:input_presence,return_value
# lokalnie
python -m intract check --staged --hunks
# w CI
python -m intract validate .
python -m intract check . --format sarif --output intract.sarifEfekt: flow przechodzi od wymagań NLP, przez kontrakty intencji, do kodu i automatycznej walidacji jakości.
In addition to inline annotations, Intract supports two ways of defining quality gates and intent contracts:
- Inline Comments: Using
@intract.v1in source files (with#,//,--, or HTML comment prefixes). - Inline Decorators: Bare
@intract.v1 ...lines or Rust#[intract.v1 ...]attributes on the line above the governed block. - External manifests (Toon Manifests): Decoupled files (
.toonorintract.toon.yaml) that specify precise coordinates (targets) for files, functions, lines, and XPaths.
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
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: addWięcej informacji i pełne przykłady znajdziesz w katalogu examples/toon/.
Start here:
- Docs index
- Getting Started
- Commands Reference
- Contract Format
- Manifest
intract.yaml - Architecture
- Validation Model
- Watch & Engine
- Plugins
- Integrations
- Roadmap
- SUMD Descriptor
Dokument SUMD.md jest źródłem opisu operacyjnego projektu (workflow, pipeline jakości, interfejsy, env).
Architecture flow:
SUMD (description) -> DOQL/source (code) -> taskfile (automation) -> testql (verification)
Interfaces:
- CLI entry points:
intract,intract-mcp - testql scenarios:
testql-scenarios/generated-cli-tests.testql.toon.yaml
Quality pipeline (pyqual.yaml) — najważniejsze etapy:
test(python -m pytest -q --tb=short)intract_contracts(validate,check,duplicatesnaexamples/full-stack)intract_artifacts(scan --all-artifacts --jsondo.pyqual/artifacts.json)intract_web_app(validateiscandlaexamples/web-app/iterations/v1-pass+run-demo.sh)intract_demo_ci(bash scripts/ci-full-stack.sh)
Environment variables (.env.example) używane w automatyzacji:
OPENROUTER_API_KEYLLM_MODELPFIX_AUTO_APPLY,PFIX_AUTO_INSTALL_DEPS,PFIX_AUTO_RESTARTPFIX_MAX_RETRIES,PFIX_DRY_RUN,PFIX_ENABLEDPFIX_GIT_COMMIT,PFIX_GIT_PREFIX,PFIX_CREATE_BACKUPS
Release and build references:
goal.yaml(semver, conventional commits, changelog)Makefiletargets:install,test,lint,format- analysis artifacts:
project/map.toon.yaml,project/context.md,project/prompt.txt
Core:
src/intract/src/intract/models.pysrc/intract/parser.pysrc/intract/signature.pysrc/intract/validation.py
Operational modules:
src/intract/cli.pysrc/intract/config.pysrc/intract/policy.pysrc/intract/git.pysrc/intract/watch.py
Analysis engine:
src/intract/engine/src/intract/engine/scanner.pysrc/intract/engine/analyzer.pysrc/intract/engine/assigner.pysrc/intract/engine/drift.pysrc/intract/engine/monitor.py
Plugins and integrations:
src/intract/plugins/src/intract/integrations/src/intract/integrations/planfile.pysrc/intract/artifacts.pysrc/intract/reporters/sarif.py
Schemas and templates:
schemas/intract.schema.jsontemplates/templates/intract.yamltemplates/pyproject-intract.tomltemplates/openapi.intract.yamltemplates/Dockerfile.intract
Examples:
examples/README.md— indeks wszystkich przykładówexamples/web-app/— aplikacja webowa: iteracje v1/v2 + mock UIexamples/full-stack/— graf, duplikaty intencjiexamples/integration_tests/
SDKs:
CI / packaging:
pip install -e .[dev]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 .python examples/integration_tests/run_examples.pyExpected:
example_01: pass
example_02: violation + planfile-compatible ticket
example_03: watch/engine/drift works
Generate:
python -m intract init .Validate:
python -m intract check-manifest intract.yaml
python -m intract validate . --manifest intract.yamlExample .pre-commit-config.yaml:
repos:
- repo: local
hooks:
- id: intract
name: intract intent contracts
entry: intract check --staged
language: system
pass_filenames: falsepython -m intract check . --format sarif --output intract.sarifGitHub workflow:
Licensed under Apache-2.0.