{"id":51137284,"url":"https://github.com/dgenio/intentflow","last_synced_at":"2026-06-25T19:02:32.627Z","repository":{"id":364360590,"uuid":"1264431224","full_name":"dgenio/intentflow","owner":"dgenio","description":"An experimental language for governed LLM workflows: compile goals, evidence, uncertainty, actions, and verification into auditable agent plans.","archived":false,"fork":false,"pushed_at":"2026-06-22T17:41:12.000Z","size":234,"stargazers_count":2,"open_issues_count":113,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T19:23:58.103Z","etag":null,"topics":["agent-framework","agentic-ai","agents","ai-agents","ai-safety","cli","developer-tools","dsl","llm","llmops","open-source","programming-language","prompt-engineering","python","structured-output"],"latest_commit_sha":null,"homepage":"https://github.com/dgenio/intentflow#readme","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dgenio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T22:01:00.000Z","updated_at":"2026-06-22T17:41:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dgenio/intentflow","commit_stats":null,"previous_names":["dgenio/intentflow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dgenio/intentflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fintentflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fintentflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fintentflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fintentflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dgenio","download_url":"https://codeload.github.com/dgenio/intentflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fintentflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34788254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agentic-ai","agents","ai-agents","ai-safety","cli","developer-tools","dsl","llm","llmops","open-source","programming-language","prompt-engineering","python","structured-output"],"created_at":"2026-06-25T19:02:32.048Z","updated_at":"2026-06-25T19:02:32.606Z","avatar_url":"https://github.com/dgenio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IntentFlow\n\n**A language for governed cognitive processes.**\n\n\u003e Python programs deterministic computation.\n\u003e IntentFlow programs governed cognition.\n\nIntentFlow is not a chatbot wrapper and not a prompt template. It is a\nsmall language that compiles cognitive intent — a goal, its evidence\nrequirements, its action policy, its verification rules, its uncertainty\nhandling, and its typed output contract — into an **auditable, governed,\nexecutable agent plan**. The runtime executes that plan through explicit\nphases and emits a hash-chained trace that a third party can independently\nverify.\n\n```text\n.iflow source -\u003e parser -\u003e analyzer (IFLOW diagnostics) -\u003e compiler -\u003e\nexecution plan (JSON) -\u003e runtime (13-phase machine) -\u003e traced result -\u003e\nreplay / audit\n```\n\n## Install\n\n```bash\npip install -e .            # core: zero runtime dependencies\npip install -e \".[dev]\"     # + pytest\npip install -e \".[openai]\"  # + OpenAI-compatible backend\npip install -e \".[llm]\"     # + Anthropic backend\n```\n\n## Quickstart\n\n```bash\nintentflow validate examples/opensource_triage.iflow\nintentflow inspect  examples/opensource_triage.iflow\nintentflow explain  examples/opensource_triage.iflow\nintentflow compile  examples/opensource_triage.iflow --out plan.json\nintentflow run      examples/opensource_triage.iflow --backend simulate --trace-dir traces\nintentflow replay   traces/TriageGitHubIssue-*.json\nintentflow audit    examples/opensource_triage.iflow traces/TriageGitHubIssue-*.json\n```\n\nEvery command above works offline, deterministically, with no API key.\n\n## First example\n\n```text\ngoal TriageGitHubIssue {\n  objective:\n    triage a GitHub issue safely and propose a maintainer-ready response\n\n  context:\n    max_tokens 10000\n    prefer recent_comments\n    preserve maintainer_intent\n\n  evidence:\n    require issue_body\n    require comments\n    require repo_context\n    optional related_issues\n    distrust unsupported_claims\n\n  actions:\n    allow read_issue\n    allow search_repo\n    allow draft_comment\n    require_approval post_comment\n    deny close_issue\n\n  verify:\n    require cites_evidence\n    require maintainer_safe_tone\n    require no_unverified_claims\n    check confidence \u003e= 0.65\n\n  uncertainty:\n    if confidence \u003c 0.65 ask_human\n    if missing_evidence ask_human\n    if security_risk block_action\n\n  output:\n    summary: string\n    likely_cause: string?\n    confidence: number\n    suggested_response: markdown\n    proposed_labels: list[string]\n}\n```\n\nReading this file tells you — and `intentflow explain` will say it in plain\nEnglish — what the goal is, what evidence is mandatory, what the agent may\ndo, what is forbidden, what needs a human, how the result is checked, and\nexactly what typed output it promises.\n\n## Language concepts\n\n| Concern | Section | Enforced by |\n| --- | --- | --- |\n| Goal | `objective:` | analyzer (required) |\n| Context policy | `context:` | runtime (prompt plan), analyzer bounds |\n| Evidence | `evidence:` (`require`/`optional`/`prefer`/`distrust`) | action gate + `missing_evidence` signal |\n| Reasoning discipline | `model:` | prompt plan |\n| Action governance | `actions:` (`allow`/`require_approval`/`deny`) | the `ActionGate`, outside the model |\n| Verification | `verify:` (`check`, `require`, free text) | machine checks + judged tier |\n| Uncertainty | `uncertainty:` (`if \u003ccond\u003e \u003caction\u003e`) | run status control flow |\n| Output contract | `output:` (typed fields) | implicit `V0` schema check |\n\nTyped output fields are part of the language: `string`, `number`,\n`boolean`, `markdown` (each with optional `?`), `list[string]`,\n`list[number]`, `object`, `object?`. The full grammar, diagnostics table,\nand invalid examples live in [`docs/language_spec.md`](docs/language_spec.md).\n\n## CLI\n\n| Command | Purpose |\n| --- | --- |\n| `intentflow parse \u003cfile\u003e` | print the AST as JSON |\n| `intentflow validate \u003cfile\u003e [--json]` | static analyzer: coded diagnostics (IFLOW001–022) |\n| `intentflow lint \u003cfile\u003e [--strict]` | advisory tier only (warnings/info) |\n| `intentflow compile \u003cfile\u003e [--out plan.json]` | emit the versioned execution plan |\n| `intentflow inspect \u003cfile\u003e [--json]` | at-a-glance summary of a goal |\n| `intentflow explain \u003cfile\u003e [--json]` | translate the program into plain English |\n| `intentflow format \u003cfile\u003e [--check\\|--write]` | idempotent canonical formatter |\n| `intentflow run \u003cfile\u003e [...]` | execute through the 13-phase runtime |\n| `intentflow replay \u003ctrace.json\u003e [--json]` | readable summary of a saved trace |\n| `intentflow audit \u003cfile\u003e \u003cresult.json\u003e` | independently verify a run against the plan |\n\n`run` flags: `--backend simulate|mock|openai|anthropic|replay`, `--goal`,\n`--pipeline`, `--workspace DIR`, `--approve ACTION`,\n`--approve-interactive`, `--approve-webhook URL`, `--judge`,\n`--cassette/--record-cassette`, `--sign-trace`, `--trace-dir`,\n`--trace-out`, `--json`, `--verbose`.\n\n## Run statuses\n\nEvery run ends in exactly one status, and the exit code follows it:\n\n| Status | Meaning | Exit |\n| --- | --- | --- |\n| `completed` | output produced, verification passed | 0 |\n| `needs_human` | an uncertainty rule escalated (`ask_human`) | 0 |\n| `blocked` | policy stopped the run (`block_action`) | 1 |\n| `failed_validation` | analyzer errors; nothing executed | 1 |\n| `failed_verification` | a machine check failed | 1 |\n| `backend_error` | backend failed / unusable output | 1 |\n\nThe runtime can never report a failed verification as success — the auditor\nchecks for exactly that cover-up (violation `S1`/`V1`).\n\n## Simulation mode (default)\n\nThe `simulate` backend is deterministic mock cognition: it honors the\ngoal's typed output schema, cites the evidence that was actually collected,\nreports a fixed raw confidence (0.72, calibrated to 0.676), and labels\neverything `[simulated]`. It exists so the *control structure* — gating,\ncalibration, verification, escalation, tracing — is testable end to end\nwith no network.\n\nThe core package is intentionally dependency-free; see\n[`docs/architecture.md#zero-runtime-dependency-core`](docs/architecture.md#zero-runtime-dependency-core)\nfor the policy and test guard.\n\n```bash\nintentflow run examples/production_diagnosis.iflow \\\n    --workspace examples/workspace --trace-dir traces --verbose\n# -\u003e needs_human: calibrated confidence 0.676 \u003c 0.7, by design\n```\n\nWith `--workspace`, evidence is collected by real read-only tools *through\nthe action gate*: a goal that requires `logs` but does not allow\n`read_logs` gets a traced `action_blocked` and a `missing_evidence` signal\n— not the file contents.\n\n## Real backend mode\n\n```bash\nOPENAI_API_KEY=... intentflow run examples/opensource_triage.iflow --backend openai\nANTHROPIC_API_KEY=... intentflow run examples/opensource_triage.iflow --backend anthropic\n```\n\nReal backends sit behind the identical governance path and return a full\n`BackendResponse` (raw text, parsed JSON, model, latency, token usage,\nfinish reason). The OpenAI-compatible backend honors `OPENAI_BASE_URL` /\n`OPENAI_MODEL` (Azure, vLLM, Ollama) and requests structured JSON output.\n`--record-cassette` captures real replies; `--backend replay --cassette`\nreplays them deterministically in CI with no keys.\n\n## Traces, replay, audit\n\n`--trace-dir` writes a self-contained artifact per run: trace id,\ntimestamp, source path + hash, plan hash, backend, status, all 13 phases,\ndiagnostics, messages, evidence, the backend response, parsed output,\nverification results, uncertainty decisions, action-gate decisions, and the\nhash-chained event log (optionally HMAC-signed with `--sign-trace`).\n\n```bash\nintentflow replay traces/TriageGitHubIssue-*.json   # the run as a story\nintentflow audit  examples/opensource_triage.iflow traces/TriageGitHubIssue-*.json\n```\n\n`audit` recompiles the source and proves — without trusting the runtime,\nthe backend, or the model — that no denied action ran, every gated action\nhad a prior approval, every citation points at collected evidence, no\nverification failure was hidden, the status is consistent with the trace,\nand the trace chain is intact.\n\n## Use from Python\n\n```python\nimport intentflow\n\nprogram = intentflow.load(\"examples/opensource_triage.iflow\")\nresult = program.run(backend=\"simulate\")\nassert result[\"status\"] == \"completed\"\n\n# register a Python function as a governed action (runs through the gate):\nprogram.register_tool(\"lookup_user\", serves=(\"user_record\",),\n                      handler=lambda src: \"enterprise plan\")\n\nreport = intentflow.audit_document(program.compile(), result)\nassert report[\"conformant\"]\n```\n\nSix examples ship with the repo: `examples/code_review.iflow`,\n`examples/high_risk_deploy.iflow`, `examples/incident_pipeline.iflow`,\n`examples/opensource_triage.iflow`, `examples/production_diagnosis.iflow`,\nand `examples/research_synthesis.iflow`, plus `examples/workspace/` with\nreal evidence files for governed collection. The test suite runs every\nexample against that workspace so required evidence sources stay backed by\nfiles instead of simulated placeholders.\n\n## Design philosophy\n\nThe honest objection to any \"agent DSL\" is: *couldn't this be a Python\ndataclass?* A dataclass can hold the same fields; it cannot give them\nsemantics that survive the model boundary. IntentFlow's answer:\n\n1. **The program is a contract.** `deny close_issue` is enforced by the\n   `ActionGate` outside the model. The gate never reads model output, so\n   the model cannot talk its way past it.\n2. **The trace is a witness.** Every run emits a hash-chained, optionally\n   signed event log in a defined format.\n3. **Conformance is independently verifiable.** `intentflow audit` proves a\n   run stayed inside its envelope using only the source and the trace.\n\nSee [`docs/design_principles.md`](docs/design_principles.md).\n\n### Compared to the alternatives\n\n| | What you write | Where governance lives | Auditable? |\n| --- | --- | --- | --- |\n| **Python function** | exact instructions | in your code | yes, but it isn't cognition |\n| **Prompt template** | interpolated strings | prose the model may ignore | output only |\n| **Agent framework** | functions to wire up | your head + your prompts | ad-hoc logging |\n| **IntentFlow goal** | evidence, actions, checks, uncertainty, typed output | compiled program text, enforced outside the model | every run emits a replayable witness |\n\n## Examples\n\nFive programs ship with the repo — see [`docs/examples.md`](docs/examples.md):\n\n* [`opensource_triage.iflow`](examples/opensource_triage.iflow) — flagship; completes.\n* [`production_diagnosis.iflow`](examples/production_diagnosis.iflow) — escalates to a human by design.\n* [`code_review.iflow`](examples/code_review.iflow) — typed structured review output.\n* [`research_synthesis.iflow`](examples/research_synthesis.iflow) — intentionally triggers analyzer warnings.\n* [`high_risk_deploy.iflow`](examples/high_risk_deploy.iflow) — intentionally `blocked` by policy.\n* [`incident_pipeline.iflow`](examples/incident_pipeline.iflow) — two goals composed with a statically checked evidence chain.\n\n## Honest status \u0026 current limitations\n\nThis is an experimental but working language. Known limits (also in the\nspec): line-oriented grammar, no compound conditions, calibration is a\nfixed shrinkage map, `object` outputs are untyped inside, uncertainty\nprimitives beyond `ask_human`/`block_action` are recorded but not executed,\nside-effecting tools are governed but not yet executed, and pipelines are\nlinear. The simulator mocks cognition; it never pretends otherwise.\n\n## Roadmap\n\nRoadmap ownership now lives in [ROADMAP.md](ROADMAP.md).\n\nFor the architecture model and design notes, see\n[`docs/architecture.md`](docs/architecture.md).\n\n## Project layout\n\n```text\nintentflow/\n  iflow_ast.py    syntactic AST + typed cognitive IR (JSON-serializable)\n  parser.py       .iflow -\u003e AST (line/column errors, strings, comments)\n  analyzer.py     static analyzer: coded diagnostics IFLOW001-022\n  actions.py      action registry: side-effect/risk metadata + heuristics\n  compiler.py     AST -\u003e versioned execution plan (risk profile, prompt plan)\n  backends.py     BackendResponse contract: simulate/mock/openai/anthropic/replay\n  judges.py       LLM-judge runner for 'judged' verification rules\n  tools.py        governed tools, the ActionGate, approval channels\n  runtime.py      13-phase machine, 6 statuses, hash-chained trace\n  auditor.py      independent trace conformance checking\n  explain.py      plain-English rendering of a program\n  formatter.py    canonical, idempotent, comment-preserving formatter\n  api.py          Python embedding (load / run / register_tool)\n  cli.py          parse|validate|lint|compile|inspect|explain|format|run|replay|audit\nexamples/         six programs + a real evidence workspace\ntests/            ~230 tests; no network, no API keys\ndocs/             language spec, design principles, examples, roadmap\n```\n\n## Citing IntentFlow\n\nIntentFlow includes [`CITATION.cff`](CITATION.cff) so GitHub can render\nrepository citation metadata. For papers and reports, cite the repository\nversion you used. For example:\n\n```bibtex\n@software{intentflow,\n  title = {IntentFlow},\n  author = {{IntentFlow contributors}},\n  version = {0.6.0},\n  url = {https://github.com/dgenio/intentflow},\n  note = {An experimental language for governed cognitive processes}\n}\n```\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgenio%2Fintentflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdgenio%2Fintentflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgenio%2Fintentflow/lists"}