doctrine-agents 1.0.2__tar.gz

doctrine_agents-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aelaguiz
+
+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.

doctrine_agents-1.0.2/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: doctrine-agents
+Version: 1.0.2
+Summary: Typed DSL and compiler for reusable AI agent instructions and workflows that compile to AGENTS.md.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aelaguiz/doctrine
+Project-URL: Documentation, https://github.com/aelaguiz/doctrine/tree/main/docs
+Project-URL: Repository, https://github.com/aelaguiz/doctrine
+Project-URL: Issues, https://github.com/aelaguiz/doctrine/issues
+Project-URL: Changelog, https://github.com/aelaguiz/doctrine/blob/main/CHANGELOG.md
+Project-URL: Discussions, https://github.com/aelaguiz/doctrine/discussions
+Project-URL: Security, https://github.com/aelaguiz/doctrine/security/policy
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: interegular<1,>=0.3
+Requires-Dist: lark<2,>=1.2
+Dynamic: license-file
+
+# Doctrine
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.14%2B](https://img.shields.io/badge/python-3.14%2B-3776AB.svg)](pyproject.toml)
+[![CI](https://img.shields.io/github/actions/workflow/status/aelaguiz/doctrine/ci.yml?branch=main&label=ci)](https://github.com/aelaguiz/doctrine/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/doctrine-agents.svg)](https://pypi.org/project/doctrine-agents/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aelaguiz/doctrine/badge)](https://scorecard.dev/viewer/?uri=github.com/aelaguiz/doctrine)
+[![Output: AGENTS.md](https://img.shields.io/badge/output-AGENTS.md-6E56CF.svg)](https://github.com/aelaguiz/doctrine)
+
+[Docs](docs/README.md) · [Versioning](docs/VERSIONING.md) · [Changelog](CHANGELOG.md) · [Rally](https://github.com/aelaguiz/rally) · [VS Code extension](editors/vscode/README.md)
+
+Write agent flows as code. Compile them to `AGENTS.md`.
+
+Doctrine is a typed DSL and compiler for reusable agent instructions, workflows, reviews, skills, and I/O contracts. Instead of hand-editing giant `AGENTS.md` files, you author small `.prompt` files and compile deterministic runtime artifacts that current coding-agent tools can already read today.
+
+<p align="center">
+  <img src="docs/assets/readme-doctrine-agent-example.png" alt="Side-by-side view of Doctrine source on the left and compiled AGENTS.md output on the right." width="1200">
+</p>
+
+Why teams reach for Doctrine:
+
+- one shared rule changes once
+- compile-time failures catch drift before runtime
+- humans can review source and emitted runtime side by side
+- flow diagrams, verification, and editor support ship today
+
+## Doctrine and Rally
+
+- Use Doctrine when you want to author and validate the flow.
+- Use Rally when you want to run that flow with repo-local state, resumability, and strict turn routing.
+- The split is deliberate: Doctrine is the authoring layer, Rally is the runtime layer.
+
+## Why Doctrine exists
+
+Serious agent systems drift fast when the source of truth is copied Markdown:
+
+- shared sections get duplicated and then edited out of sync
+- one policy fix turns into search-and-hope edits
+- large prompt trees become hard to review
+- runtime Markdown is the delivery format, not the right authoring surface
+
+Doctrine turns that into a language and compiler problem.
+
+## Quick example
+
+```prompt
+workflow SharedTurn: "How To Take A Turn"
+    "Read the current brief before you act."
+    "Leave one honest handoff and stop."
+
+skill RepoSearchSkill: "repo-search"
+    purpose: "Find the right repo surface for the current job."
+
+abstract agent ReviewRole:
+    read_first: SharedTurn
+
+agent BriefReviewer[ReviewRole]:
+    role: "Core job: review the current brief and route the same issue honestly."
+
+    inherit read_first
+
+    skills: "Skills"
+        can_run: "Can Run"
+            skill search: RepoSearchSkill
+                requirement: Advisory
+```
+
+That compiles to runtime Markdown:
+
+```md
+Core job: review the current brief and route the same issue honestly.
+
+## How To Take A Turn
+
+Read the current brief before you act.
+Leave one honest handoff and stop.
+
+## Skills
+
+### Can Run
+
+#### repo-search
+```
+
+## Quickstart
+
+Source checkout is still the full setup path for contributor proof, the
+example corpus, and `emit_flow`.
+
+When Doctrine is installed from a package index, the distribution name is
+`doctrine-agents`. The Python module name stays `doctrine`.
+
+Want the packaged compiler instead of a source checkout?
+
+```bash
+python -m pip install doctrine-agents
+```
+
+```bash
+git clone https://github.com/aelaguiz/doctrine.git
+cd doctrine
+uv sync
+npm ci
+make check
+```
+
+Want a smaller first proof?
+
+```bash
+uv run --locked python -m doctrine.verify_corpus --manifest examples/01_hello_world/cases.toml
+```
+
+Want generated output right away?
+
+```bash
+uv run --locked python -m doctrine.emit_docs --target example_07_handoffs
+uv run --locked python -m doctrine.emit_flow --target example_73_flow_visualizer_showcase
+```
+
+## What ships today
+
+- concrete and abstract `agent` declarations
+- reusable and inherited `workflow` declarations
+- first-class `review` and `abstract review` declarations
+- typed `skills`, `inputs`, `outputs`, and JSON-schema-backed contracts
+- imports, readable refs, interpolation, enums, and workflow law
+- `emit_docs`, `emit_flow`, and `emit_skill`
+- manifest-backed verification through `examples/106_review_split_final_output_json_schema_partial`
+- a repo-local VS Code extension for `.prompt` files
+
+## Workflow visualizer
+
+<p align="center">
+  <img src="examples/73_flow_visualizer_showcase/build_ref/AGENTS.flow.svg" alt="Generated Doctrine workflow diagram showing shared inputs, a route-first handoff lane, and compiler-owned flow output." width="1200">
+</p>
+
+The checked-in showcase above comes from `examples/73_flow_visualizer_showcase`. It proves that Doctrine can emit human-readable runtime docs and compiler-owned flow diagrams from the same source graph.
+
+## Read next
+
+- [docs/README.md](docs/README.md)
+- [docs/VERSIONING.md](docs/VERSIONING.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [docs/WHY_DOCTRINE.md](docs/WHY_DOCTRINE.md)
+- [docs/LANGUAGE_REFERENCE.md](docs/LANGUAGE_REFERENCE.md)
+- [docs/EMIT_GUIDE.md](docs/EMIT_GUIDE.md)
+- [examples/README.md](examples/README.md)
+- [editors/vscode/README.md](editors/vscode/README.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Questions and contributions
+
+- Use [Discussions](https://github.com/aelaguiz/doctrine/discussions) for questions and design talk.
+- Use [Issues](https://github.com/aelaguiz/doctrine/issues) for clear bugs or scoped proposals.
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and proof commands.
+- See [SUPPORT.md](SUPPORT.md) for help paths, [SECURITY.md](SECURITY.md) for private vulnerability reports, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for collaboration rules.
+
+If this direction is useful, star the repo and watch releases.

doctrine_agents-1.0.2/README.md

@@ -0,0 +1,158 @@
+# Doctrine
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.14%2B](https://img.shields.io/badge/python-3.14%2B-3776AB.svg)](pyproject.toml)
+[![CI](https://img.shields.io/github/actions/workflow/status/aelaguiz/doctrine/ci.yml?branch=main&label=ci)](https://github.com/aelaguiz/doctrine/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/doctrine-agents.svg)](https://pypi.org/project/doctrine-agents/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aelaguiz/doctrine/badge)](https://scorecard.dev/viewer/?uri=github.com/aelaguiz/doctrine)
+[![Output: AGENTS.md](https://img.shields.io/badge/output-AGENTS.md-6E56CF.svg)](https://github.com/aelaguiz/doctrine)
+
+[Docs](docs/README.md) · [Versioning](docs/VERSIONING.md) · [Changelog](CHANGELOG.md) · [Rally](https://github.com/aelaguiz/rally) · [VS Code extension](editors/vscode/README.md)
+
+Write agent flows as code. Compile them to `AGENTS.md`.
+
+Doctrine is a typed DSL and compiler for reusable agent instructions, workflows, reviews, skills, and I/O contracts. Instead of hand-editing giant `AGENTS.md` files, you author small `.prompt` files and compile deterministic runtime artifacts that current coding-agent tools can already read today.
+
+<p align="center">
+  <img src="docs/assets/readme-doctrine-agent-example.png" alt="Side-by-side view of Doctrine source on the left and compiled AGENTS.md output on the right." width="1200">
+</p>
+
+Why teams reach for Doctrine:
+
+- one shared rule changes once
+- compile-time failures catch drift before runtime
+- humans can review source and emitted runtime side by side
+- flow diagrams, verification, and editor support ship today
+
+## Doctrine and Rally
+
+- Use Doctrine when you want to author and validate the flow.
+- Use Rally when you want to run that flow with repo-local state, resumability, and strict turn routing.
+- The split is deliberate: Doctrine is the authoring layer, Rally is the runtime layer.
+
+## Why Doctrine exists
+
+Serious agent systems drift fast when the source of truth is copied Markdown:
+
+- shared sections get duplicated and then edited out of sync
+- one policy fix turns into search-and-hope edits
+- large prompt trees become hard to review
+- runtime Markdown is the delivery format, not the right authoring surface
+
+Doctrine turns that into a language and compiler problem.
+
+## Quick example
+
+```prompt
+workflow SharedTurn: "How To Take A Turn"
+    "Read the current brief before you act."
+    "Leave one honest handoff and stop."
+
+skill RepoSearchSkill: "repo-search"
+    purpose: "Find the right repo surface for the current job."
+
+abstract agent ReviewRole:
+    read_first: SharedTurn
+
+agent BriefReviewer[ReviewRole]:
+    role: "Core job: review the current brief and route the same issue honestly."
+
+    inherit read_first
+
+    skills: "Skills"
+        can_run: "Can Run"
+            skill search: RepoSearchSkill
+                requirement: Advisory
+```
+
+That compiles to runtime Markdown:
+
+```md
+Core job: review the current brief and route the same issue honestly.
+
+## How To Take A Turn
+
+Read the current brief before you act.
+Leave one honest handoff and stop.
+
+## Skills
+
+### Can Run
+
+#### repo-search
+```
+
+## Quickstart
+
+Source checkout is still the full setup path for contributor proof, the
+example corpus, and `emit_flow`.
+
+When Doctrine is installed from a package index, the distribution name is
+`doctrine-agents`. The Python module name stays `doctrine`.
+
+Want the packaged compiler instead of a source checkout?
+
+```bash
+python -m pip install doctrine-agents
+```
+
+```bash
+git clone https://github.com/aelaguiz/doctrine.git
+cd doctrine
+uv sync
+npm ci
+make check
+```
+
+Want a smaller first proof?
+
+```bash
+uv run --locked python -m doctrine.verify_corpus --manifest examples/01_hello_world/cases.toml
+```
+
+Want generated output right away?
+
+```bash
+uv run --locked python -m doctrine.emit_docs --target example_07_handoffs
+uv run --locked python -m doctrine.emit_flow --target example_73_flow_visualizer_showcase
+```
+
+## What ships today
+
+- concrete and abstract `agent` declarations
+- reusable and inherited `workflow` declarations
+- first-class `review` and `abstract review` declarations
+- typed `skills`, `inputs`, `outputs`, and JSON-schema-backed contracts
+- imports, readable refs, interpolation, enums, and workflow law
+- `emit_docs`, `emit_flow`, and `emit_skill`
+- manifest-backed verification through `examples/106_review_split_final_output_json_schema_partial`
+- a repo-local VS Code extension for `.prompt` files
+
+## Workflow visualizer
+
+<p align="center">
+  <img src="examples/73_flow_visualizer_showcase/build_ref/AGENTS.flow.svg" alt="Generated Doctrine workflow diagram showing shared inputs, a route-first handoff lane, and compiler-owned flow output." width="1200">
+</p>
+
+The checked-in showcase above comes from `examples/73_flow_visualizer_showcase`. It proves that Doctrine can emit human-readable runtime docs and compiler-owned flow diagrams from the same source graph.
+
+## Read next
+
+- [docs/README.md](docs/README.md)
+- [docs/VERSIONING.md](docs/VERSIONING.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [docs/WHY_DOCTRINE.md](docs/WHY_DOCTRINE.md)
+- [docs/LANGUAGE_REFERENCE.md](docs/LANGUAGE_REFERENCE.md)
+- [docs/EMIT_GUIDE.md](docs/EMIT_GUIDE.md)
+- [examples/README.md](examples/README.md)
+- [editors/vscode/README.md](editors/vscode/README.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Questions and contributions
+
+- Use [Discussions](https://github.com/aelaguiz/doctrine/discussions) for questions and design talk.
+- Use [Issues](https://github.com/aelaguiz/doctrine/issues) for clear bugs or scoped proposals.
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and proof commands.
+- See [SUPPORT.md](SUPPORT.md) for help paths, [SECURITY.md](SECURITY.md) for private vulnerability reports, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for collaboration rules.
+
+If this direction is useful, star the repo and watch releases.

doctrine_agents-1.0.2/doctrine/__init__.py

@@ -0,0 +1,10 @@
+"""Doctrine language bootstrap package."""
+
+from doctrine.diagnostics import CompileError, EmitError, ParseError, DoctrineError
+
+__all__ = [
+    "CompileError",
+    "EmitError",
+    "ParseError",
+    "DoctrineError",
+]

doctrine_agents-1.0.2/doctrine/_compiler/__init__.py

@@ -0,0 +1 @@
+"""Internal compiler package; top-level operator imports should stay on doctrine.compiler."""

doctrine_agents-1.0.2/doctrine/_compiler/compile/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from doctrine._compiler.compile.agent import CompileAgentMixin
+from doctrine._compiler.compile.final_output import CompileFinalOutputMixin
+from doctrine._compiler.compile.outputs import CompileOutputsMixin
+from doctrine._compiler.compile.readable_blocks import CompileReadableBlocksMixin
+from doctrine._compiler.compile.readables import CompileReadablesMixin
+from doctrine._compiler.compile.records import CompileRecordsMixin
+from doctrine._compiler.compile.review_cases import CompileReviewCasesMixin
+from doctrine._compiler.compile.review_contract import CompileReviewContractMixin
+from doctrine._compiler.compile.reviews import CompileReviewsMixin
+from doctrine._compiler.compile.skill_package import CompileSkillPackageMixin
+from doctrine._compiler.compile.workflows import CompileWorkflowsMixin
+
+
+class CompileMixin(
+    CompileWorkflowsMixin,
+    CompileReviewCasesMixin,
+    CompileReviewContractMixin,
+    CompileReviewsMixin,
+    CompileRecordsMixin,
+    CompileOutputsMixin,
+    CompileReadableBlocksMixin,
+    CompileAgentMixin,
+    CompileReadablesMixin,
+    CompileFinalOutputMixin,
+    CompileSkillPackageMixin,
+):
+    """Compile helper boundary for CompilationContext."""