Cognitive Modules

Verifiable Structured AI Task Specification

English | 中文

Cognitive Modules is a specification and runtime for verifiable, structured AI tasks with strong contracts, auditability, and deterministic validation.

Status

• Primary runtime: Node.js CLI (cognitive-modules-cli, via npx cogn@<version> ...)

Version

• Runtime (npm): 2.2.16
• Spec: v2.2

Roadmap

The product direction and release plan are tracked in ROADMAP.md.

• v2.2.x - stabilize the current runtime, tighten defaults, and close consistency bugs
• v2.3 - make the product easier to understand and lead with killer use cases
• v2.4 - open the protocol surface for compatible providers and runtimes

Installation (Node.js)

# Zero-install quick start
npx cogn@2.2.16 --help

# Or use the full package name
npx cognitive-modules-cli@2.2.16 --help

# Global installation
npm install -g cogn@2.2.16
# or: npm install -g cognitive-modules-cli@2.2.16

cogn is an alias package for cognitive-modules-cli. Docs use npx cogn@<version> ... as the canonical entrypoint.

Registry Index ("Latest" Strategy)

By default, the CLI fetches the registry index from the latest GitHub Release asset:

• https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json

For reproducible builds, pin to a specific tag:

• https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json

Override via:

• Env: COGNITIVE_REGISTRY_URL
• Env: COGNITIVE_REGISTRY_TIMEOUT_MS (ms)
• Env: COGNITIVE_REGISTRY_MAX_BYTES
• CLI: --registry <url>
• CLI: --registry-timeout-ms <ms>
• CLI: --registry-max-bytes <n>

Quick Start

# Configure a provider (example: OpenAI)
export OPENAI_API_KEY=sk-xxx

# 5-minute path: run a one-file "Core" module from stdin (prints a v2.2 envelope)
cat <<'EOF' | npx cogn@2.2.16 core run --stdin --args "hello" --pretty
Return a valid v2.2 envelope (meta + data). Put your answer in data.result.
EOF

Notes:

• The recommended, unambiguous entrypoint is npx cogn@2.2.16 ... (avoids any cog binary conflicts on your machine).
• When passing --provider/--model, put them after the command, e.g. ... core run --stdin --provider minimax --model MiniMax-M2.1 ....
• If multiple provider API keys are set, the CLI auto-selects a provider by priority order. Use --provider ... (recommended) or unset GEMINI_API_KEY (etc.) to avoid surprises.

Primary Use Case: PR Risk Gate

The sharpest Cognitive entrypoint is now PR Risk Gate: turn a PR diff into a stable merge decision contract.

Local demo:

export GEMINI_API_KEY=sk-xxx

cat <<'EOF' | npx cogn@2.2.16 pipe --module pr-risk-gate --pretty --profile standard --provider gemini --model gemini-3-pro-preview
diff --git a/auth.py b/auth.py
@@
-def login(user, password):
-    query = "SELECT * FROM users WHERE name = ? AND password = ?"
-    return db.execute(query, (user, password)).fetchone()
+def login(user, password):
+    query = f"SELECT * FROM users WHERE name = '{user}' AND password = '{password}'"
+    return db.execute(query).fetchone()
EOF

Template assets:

• Module: cognitive/modules/pr-risk-gate
• Workflow + CI script: templates/use-cases/pr-review-gate
• Docs entry: docs-v2/docs/getting-started/pr-review-gate.md

Benchmark evidence:

• raw-text fails the contract baseline in our Gemini and MiniMax runs
• cognitive-core and cognitive-standard reached schema=1, semantic=1, stability=1
• See docs-v2/docs/getting-started/benchmark-evidence.md

v2.2 Response Format

All modules return the unified v2.2 envelope format:

{
  "ok": true,
  "meta": {
    "confidence": 0.92,
    "risk": "low",
    "explain": "Brief summary for quick routing decisions (≤280 chars)"
  },
  "data": {
    "...business fields...",
    "rationale": "Detailed reasoning for audit and human review",
    "extensions": {
      "insights": [
        {
          "text": "Additional insight",
          "suggested_mapping": "Suggested field to add to schema"
        }
      ]
    }
  }
}

Core Features

• Strong type contracts - JSON Schema validation for input/output
• Control/Data separation - meta for routing, data for business payloads
• Module tiers - exec | decision | exploration with strictness/overflow rules
• Subagent orchestration - @call:module for inter-module calls
• Composition - sequential/parallel/conditional/iterative workflows
• HTTP API & MCP - first-class integrations for workflows and AI tools
• Repair pass - auto-fix common envelope format issues

CLI Commands

# Recommended (no global install needed):
# npx cogn@2.2.16 <command> ...

# Module management
npx cogn@2.2.16 list
npx cogn@2.2.16 add <url> --module <path>
npx cogn@2.2.16 update <module>
npx cogn@2.2.16 remove <module>
npx cogn@2.2.16 versions <url>

# Run modules
npx cogn@2.2.16 run <module> --args "..."
npx cogn@2.2.16 run <module> --input '{"query":"..."}'

# Composition
npx cogn@2.2.16 compose <module> --args "..."
npx cogn@2.2.16 compose-info <module>

# Validation & migration
npx cogn@2.2.16 validate <module> --v22
npx cogn@2.2.16 validate --all
npx cogn@2.2.16 migrate <module> --dry-run
npx cogn@2.2.16 migrate --all --no-backup

# Other
npx cogn@2.2.16 pipe --module <name>
npx cogn@2.2.16 init [name]
npx cogn@2.2.16 doctor
npx cogn@2.2.16 serve --port 8000
npx cogn@2.2.16 mcp

Built-in Modules (Repository)

Module	Tier	Function	Example
pr-risk-gate	decision	PR merge gate contract	npx cogn@2.2.16 pipe --module pr-risk-gate --profile standard
code-reviewer	decision	Code review	npx cogn@2.2.16 run code-reviewer --args "your code"
code-simplifier	decision	Code simplification	npx cogn@2.2.16 run code-simplifier --args "complex code"
task-prioritizer	decision	Task priority sorting	npx cogn@2.2.16 run task-prioritizer --args "task1,task2"
api-designer	decision	REST API design	npx cogn@2.2.16 run api-designer --args "order system"
ui-spec-generator	exploration	UI spec generation	npx cogn@2.2.16 run ui-spec-generator --args "e-commerce homepage"
ui-component-generator	exploration	UI component spec	npx cogn@2.2.16 run ui-component-generator --args "button component"
product-analyzer	exploration	Product analysis	npx cogn@2.2.16 run product-analyzer --args "health product"

Module Format (v2.2)

my-module/
├── module.yaml     # Machine-readable manifest
├── prompt.md       # Human-readable prompt
├── schema.json     # meta + input + data + error schemas
└── tests/          # Golden test cases

Minimal module.yaml:

name: my-module
version: 2.2.0
responsibility: One-line description

tier: decision                # exec | decision | exploration
schema_strictness: medium     # high | medium | low

excludes:
  - things not to do

policies:
  network: deny
  filesystem_write: deny
  side_effects: deny

overflow:
  enabled: true
  recoverable: true
  max_items: 5
  require_suggested_mapping: true

enums:
  strategy: extensible        # strict | extensible

failure:
  contract: error_union
  partial_allowed: true

compat:
  accepts_v21_payload: true
  runtime_auto_wrap: true

LLM Configuration

Cognitive Modules auto-selects a provider based on which API key is present (stable providers only). You can override with --provider and --model.

Environment variables:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GEMINI_API_KEY
• MINIMAX_API_KEY
• DEEPSEEK_API_KEY
• DASHSCOPE_API_KEY or QWEN_API_KEY
• COG_MODEL (override default model)

Experimental/community (not part of the stable support promise; require explicit --provider):

• MOONSHOT_API_KEY
• OLLAMA_HOST (Ollama local)

Provider Differences (Downgrade Is Expected)

Not every provider supports the same "native structured output / JSON Schema" features.

When a provider rejects native schemas (or only supports a subset), the runtime will safely downgrade native -> prompt and continue with prompt-only JSON plus post-validation. The decision is recorded in meta.policy.* for debugging and audit trails.

See docs-v2/docs/integration/providers.md.

Check config:

npx cogn@2.2.16 doctor

Development (Node.js)

# Clone
git clone https://github.com/Cognary/cognitive.git
cd cognitive

# Install
cd packages/cli-node
npm install

# Build
npm run build

# Test
npm test

Documentation

Specifications

Document	Description
SPEC-v2.2.md	v2.2 full specification
SPEC-v2.2_zh.md	v2.2 规范中文版

Implementers

Document	Description
IMPLEMENTERS-GUIDE.md	How to build a runtime
CONFORMANCE.md	Conformance levels
ERROR-CODES.md	Standard error codes
templates/runtime-starter/	Runtime starter template

Advanced

Document	Description
COMPOSITION.md	Composition and dataflow
CONTEXT-PROTOCOL.md	Context protocol
COGNITIVE-PROTOCOL.md	Protocol details
INTEGRATION.md	Integration guide

Schemas & Test Vectors

Resource	Description
spec/response-envelope.schema.json	v2.2 envelope schema
spec/module.yaml.schema.json	module.yaml schema
spec/test-vectors/	Compliance test vectors

Registry (Spec Only)

Resource	Description
REGISTRY-PROTOCOL.md	Registry protocol specification
cognitive-registry.v2.json	Default registry index (v2) tracked in main (tarballs use releases/latest strategy)
spec/registry.schema.json	Registry index schema (v2)
spec/registry-entry.schema.json	Registry entry schema

License

MIT