intentspec 0.1.0__tar.gz

intentspec-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 IntentSpec Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

intentspec-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include README.md
+graft packages
+prune packages/intentspec-ts/node_modules
+prune packages/intentspec-vscode/node_modules
+prune packages/intentspec-ts/dist
+prune packages/intentspec-vscode/dist
+recursive-include schema *.json
+recursive-include examples *.yaml *.md
+recursive-include docs *.md
+recursive-include benchmark *.py *.yaml *.md *.json
+global-exclude __pycache__
+global-exclude *.py[cod]

intentspec-0.1.0/PKG-INFO

@@ -0,0 +1,384 @@
+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).