# CogLang

CogLang is a graph-first intermediate language designed for LLM-generated graph queries and updates, with auditable execution under explicit host contracts.

Status:

- stable `v1.1.0` language core
- reference implementation
- active experimental maintenance for host/runtime ecosystem work
- host bridge v0.2 frozen only for the narrow typed write-envelope surface

Current public language release: `v1.1.0`. Current source Python distribution version: `1.1.5`. Package release notes define what is available from PyPI; source HEAD may be prepared before the remote release workflow is triggered.
HRC v0.2 is frozen for the narrow typed write-envelope surface demonstrated by `coglang host-demo` and `coglang reference-host-demo`. A minimal Node.js standard-library consumer under `examples/node_host_consumer` reads the HRC schema pack and envelope samples without importing the Python runtime. Its private npm scaffold is local example packaging evidence, not a published JavaScript SDK. An experimental in-repository Node.js minimal host/runtime stub under `examples/node_minimal_host_runtime_stub` is post-freeze example evidence, not an HRC scope expansion.

When to use CogLang:

- when you want to inspect or approve LLM-generated graph operations before they modify a knowledge graph
- when you need errors to remain explicit values instead of hidden exceptions
- when you need replayable traces for what an agent intended, submitted, and actually executed
- when you want host-side profile and capability checks before execution
- when you need a versioned host-runtime boundary for typed write-envelope submission and response evidence
- when you need a semantic-event audit layer for AI agent graph actions

When not to use CogLang:

- as a general-purpose programming language
- as a schema definition language
- as a claim that it replaces the native query language of a specific graph database
- as a tensor-level interpretability toolkit, routing debugger, metrics backend, or full observability stack

Key design choices:

- canonical M-expression text for parse determinism and inspectable generated structure
- errors as values because partial failure is common in AI-driven graph operations
- profile and capability boundaries so hosts can reject unsafe or unsupported execution paths early
- HRC v0.2 typed write-envelope evidence through `host-demo` and `reference-host-demo`
- non-Python HRC envelope consumption through `examples/node_host_consumer`, with a private npm scaffold for local `npm test` and `npm pack --dry-run`
- non-Python minimal host/runtime stub evidence through `examples/node_minimal_host_runtime_stub`, without changing HRC v0.2
- a minimal `generation-eval` fixture for checking LLM-generated CogLang outputs against parse, canonicalization, validation, top-level-head, hallucinated-operator, and maturity summaries
- a provider-neutral `generation-eval` request/response adapter for exporting prompt records and scoring external model JSON/JSONL responses without importing provider SDKs
- CogLang_Generation_Eval_Request_Response_Contract_v0_1.md as the versioned file contract for external generation-eval runners
- `examples/generation_eval_offline_runner` for a no-provider dry run and three-case contract smoke of the generation-eval response-file contract
- `examples/semantic_event_audit` for a no-provider semantic-event audit dry run that turns external graph-intent JSONL into local preflight audit records; not a protocol, hosted runner, transport envelope, or HRC expansion
- `scripts/local_ci.py` for local-first validation profiles before maintainer-triggered GitHub Actions evidence
- `examples/vscode_textmate_syntax` for companion editor-only TextMate highlighting; not a parser, validator, LSP, formatter, or normative grammar
- a minimal executor interface: second implementations should start with `execute` and `validate`; Python host-local query/dict/JSON helpers are convenience APIs, not required inheritance surface
- semantic-event audit focus: use CogLang to represent inspectable graph intents and host-visible outcomes, not every low-level model or infrastructure signal

Core documents:

- README.md: public document index and entry points
- CogLang_Quickstart_v1_1_0.md: first-pass guide and common patterns
- CogLang_Specification_v1_1_0_Draft.md: language semantics
- CogLang_Conformance_Suite_v1_1_0.md: executable examples and regression boundaries
- CogLang_Profiles_and_Capabilities_v1_1_0.md: profile and capability boundaries
- CogLang_Operator_Catalog_v1_1_0.md: operator status and call-surface summary
- CogLang_Reserved_Operator_Promotion_Criteria_v0_1.md: evidence bar for promoting Carry-forward, Reserved, or Experimental entries
- CogLang_Send_Carry_Forward_Exit_Matrix_v0_1.md: Send-specific promotion or downgrade evidence matrix; not a cross-instance protocol freeze
- CogLang_Readable_Render_Boundary_v0_1.md: boundary between canonical text, display-only readable rendering, and structured transport envelopes; not a renderer implementation
- CogLang_Readable_Render_Golden_Example_Candidates_v0_1.md: candidate readable-render examples and invariants for future renderer work; not stable renderer output
- CogLang_Readable_Render_API_Promotion_Checklist_v0_1.md: gates for promoting readable-render candidates into a public API or CLI surface; not a renderer implementation
- CogLang_HRC_Companion_Asset_Classification_v0_1.md: HRC formal versus companion asset classification; not an HRC scope expansion
- CogLang_Standalone_Install_and_Release_Guide_v0_1.md: install, build, and local release verification
- CogLang_Host_Runtime_Contract_v0_1.md: minimal host contract
- CogLang_HRC_v0_2_Final_Freeze_2026_04_28.md: host-runtime contract v0.2 frozen scope and evidence
- CogLang_HRC_v0_2_Freeze_Candidate_2026_04_28.md: prior freeze-candidate review record
- CogLang_Release_Notes_v1_1_5.md: latest Python package patch notes
- CogLang_Release_Notes_v1_1_4.md: previous Python package patch notes
- CogLang_Release_Notes_v1_1_3.md: older Python package patch notes
- CogLang_Release_Notes_v1_1_2.md: older Python package patch notes
- CogLang_Release_Notes_v1_1_1.md: older Python package patch notes
- CogLang_Release_Notes_v1_1_0.md: stable language release commitments
- CogLang_Generation_Eval_Request_Response_Contract_v0_1.md: provider-neutral request/response file contract for external generation-eval runners
- CogLang_Vision_Proposal_v0_1.md: long-term capability proposal, including v1.2 candidate themes, graph-compute governance, and AI learning maturity
- CogLang_v1_2_Evolution_Boundary_Proposal_v0_1.md: v1.2 planning boundary for semantic-action evolution, Core stability, profiles, effect preflight, graph budgets, and review bundles
- CogLang_v1_2_Effect_Budget_Preflight_Vocabulary_v0_1.md: minimal v1.2 vocabulary candidate for EffectSummary, GraphBudget, GraphBudgetEstimate, PreflightDecision, and budget-related errors; not stable v1.1 syntax
- CONTRIBUTING.md: GitHub-facing contribution entry point and validation route
- CogLang_Contribution_Guide_v0_1.md: contribution boundaries and review expectations
- examples/grammar: companion Lark and GBNF grammar examples for constrained generation; not a normative parser or validator
- examples/semantic_event_audit: companion semantic-event audit example; not a stable event schema, hosted runner, provider SDK integration, transport envelope, or HRC expansion
- examples/vscode_textmate_syntax: companion VS Code/TextMate syntax highlighting for `.coglang` files; not a parser, validator, LSP, formatter, renderer, or normative grammar
- ROADMAP.md: current direction, not a release contract
- MAINTENANCE.md: maintenance, freeze, transfer, and archive policy

Documentation language policy:

- Public-facing canonical docs are English-first.
- Chinese companion translations may appear as `.zh-CN.md` files.
- If an English document and a translation disagree, the English document, executable conformance suite, and implementation tests take precedence.

Short runnable examples:

```powershell
coglang execute 'Query[n_, Equal[Get[n_, "category"], "Person"]]'
coglang execute 'IfFound[Traverse["einstein", "born_in"], x_, x_, "unknown"]'
coglang preflight --format text 'AllNodes[]'
coglang generation-eval --summary-only
coglang generation-eval --export-requests --request-format jsonl
python scripts/local_ci.py --profile quick
coglang demo
coglang host-demo
coglang reference-host-demo
python examples/semantic_event_audit/audit_events.py examples/semantic_event_audit/fixtures/external_events.jsonl .tmp_semantic_event_audit.jsonl
node examples/node_host_consumer/consume_hrc_envelopes.mjs
npm --prefix examples/node_host_consumer test
node examples/node_minimal_host_runtime_stub/run_demo.mjs
```
