Metadata-Version: 2.4
Name: cordis-runtime
Version: 0.1.2
Summary: Minimal host runtime for Cordis Core.
Author: Cordis Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/ntoniorvn-blip/cordis
Project-URL: Issues, https://github.com/ntoniorvn-blip/cordis/issues
Project-URL: Changelog, https://github.com/ntoniorvn-blip/cordis/blob/main/CHANGELOG.md
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cordis-core<0.2,>=0.1.2
Requires-Dist: cordis-memory<0.2,>=0.1.2
Dynamic: license-file

# Cordis Runtime

Cordis Runtime is the minimal host bridge for Cordis Core. It does not call a
model and it does not split tasks.

The semantic boundary is explicit:

```text
user language
    -> host/main model interprets intent
    -> structured Task Contract
    -> Cordis Runtime + Core
    -> compact model context and control signal
```

For an agent with tool calling, the main model fills the `begin` arguments as
part of its normal turn. This does not require a second model call. A non-agent
application that accepts raw natural language must provide an optional Task
Interpreter. Task decomposition remains the responsibility of a Planner.

## Minimal use

```python
from cordis_core import CordisRuntime
from cordis_runtime import CordisHostRuntime

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

turn = runtime.begin({
    "task": {
        "goal": "Fix the login integration test",
        "domain": "software",
        "project_id": "my-app",
        "strategy_id": "inspect_logs_first",
        "stakes": "medium",
    },
    "complexity": 0.4,
    "current_step": "Inspect the failing test and logs",
    "constraints": ["Do not change the database schema"],
    "acceptance_evidence": ["login integration test passes"],
})

# Send turn["model_context"] to the host's existing planner or main model.
```

The host calls `check_action(...)` before an action, `observe(...)` for any
plan/tool/artifact/test/error event, and `finish(...)` with observable evidence
after execution. When constructed with a `CognitiveStore`, Runtime retrieves a
small project-safe snapshot on `begin`, supports deduplicated `query(...)`, and
persists the final episode through `finish(...)`.

## v0.1 boundary

Runtime provides:

- structured Task Contract validation through Core;
- task-local Focus State;
- deterministic control modes;
- compact model context;
- an experimental lexical drift heuristic, never a safety or attention guarantee;
- evidence-bound feedback delegation.
- optional `CognitiveStore` retrieval, event capture, and episode write-back.

Runtime does not provide natural-language interpretation, planning, model
calls, tool execution, durable conversation memory, or an HTTP service.

`check_action` is deliberately conservative metadata: it reports lexical
overlap and obvious destructive terms. Hosts must not treat it as semantic
understanding, an authorization decision, or a complete attention-drift guard.
