cordis-core 0.2.0

A persistent, model-agnostic cognitive core for AI agents.

Cordis Core

Cordis Core is a persistent, model-agnostic cognitive core for AI agents. It does not call models, execute tools, or own an agent loop.

Version 0.1 has one narrow purpose: make evidence from a completed task change the cognitive constraints of a later task. See ROADMAP.md for the planned Runtime and optional plugin layers.

Its closed loop is:

Task -> Preflight -> Cognitive IR -> external execution -> Evidence + Outcome
     -> Difference + Attribution -> state update -> next Preflight

Attribution is evidence-backed. A workflow can provide a reviewed attribution hint only when it agrees with the evidence kind; otherwise Cordis uses transparent evidence-kind rules and falls back to unknown rather than inventing a causal claim. Cordis then calculates the prediction difference and updates only the matching cognitive state.

Feedback is deliberately terminal and evidence-bound:

• each task ID is immutable and may receive exactly one feedback event;
• success must prove every required acceptance criterion from Preflight;
• outcomes, scores, and evidence cannot contradict one another;
• world patterns require independent observation sources, not duplicate evidence in one execution.

The core retains only state that can change a later decision:

• episodic memory: evidence-backed task experience;
• world patterns: repeated, evidence-backed external regularities;
• strategy statistics and normalized strategy entropy.

status() exposes aggregate domain and strategy state plus the most recent failed events, so a host can surface a learning failure rather than silently storing it.

Quick example

from cordis_core import CordisRuntime

runtime = CordisRuntime("cordis-state.json")

first = runtime.preflight({
    "task": {
        "goal": "Start an HTTP adapter in a clean environment",
        "domain": "software",
        "project_id": "cordis",
        "strategy_id": "import_runtime_dependencies",
    },
    "acceptance_evidence": ["clean-environment test passes"],
})

runtime.feedback({
    "task_id": first["task"]["id"],
    "outcome": "failure",
    "attribution": "strategy",
    "lesson": "Avoid import-time runtime initialization in reusable modules.",
    "evidence": [{"kind": "test", "passed": False, "summary": "clean import failed"}],
})

second = runtime.preflight({
    "task": {
        "goal": "Start an HTTP adapter in a clean environment",
        "domain": "software",
        "project_id": "cordis",
        "strategy_id": "import_runtime_dependencies",
    },
})

assert "repeat_failed_strategy:import_runtime_dependencies" in second["strategy"]["avoid"]

Development

cd cordis-core
python -m pip install -e .
python -m unittest discover -s tests -v

For a source-tree-only run, use $env:PYTHONPATH='src' before the test command. The package has no runtime dependencies.

Public API

• CordisRuntime.preflight(task) returns a serializable Cognitive IR.
• CordisRuntime.feedback(result) finalizes one task and updates state.
• CordisRuntime.status() returns observable aggregate state and recent failures.

Boundaries

Cordis Core intentionally excludes task intake, planning, model routing, tool execution, HTTP serving, and agent-specific adapters. Those belong in optional packages such as cordis-socrates, cordis-workflow, and host adapters.