Metadata-Version: 2.4
Name: cordis-core
Version: 0.1.1
Summary: A persistent, model-agnostic cognitive core for AI agents.
Author: Cordis Contributors
License: MIT
Project-URL: Homepage, https://github.com/ntoniorvn-blip/cordis
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# 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](ROADMAP.md) for the
planned Runtime and optional plugin layers.

Its closed loop is:

```text
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

```python
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

```powershell
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.
