Metadata-Version: 2.4
Name: cordis-runtime
Version: 0.4.0
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.5,>=0.4.0
Requires-Dist: cordis-memory<0.5,>=0.4.0
Dynamic: license-file

# Cordis Runtime v0.4

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
    -> difficulty policy + model context
    -> optional Planner proposes PlanIR
    -> Runtime admits plan, advances steps, then closes Core feedback
```

For an agent with tool calling, the host/main model fills the task contract as
part of its normal turn. The optional `cordis-planner` can use a model callable
to propose a PlanIR. Neither Runtime nor Planner executes a tool: Runtime owns
the deterministic workflow state and the host remains the executor.

## 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(...)`.

## Managed host lifecycle

Hosts should normally use `CordisManagedSession` instead of asking a model to
construct separate `begin`, `observe`, and `finish` calls.  The host creates
the task once, translates its own tool/test telemetry into a small typed event
set, then closes from accumulated evidence:

```python
from cordis_runtime import CordisManagedSession

session = CordisManagedSession(runtime)
turn = session.start(task_payload)

# The host, not the model, emits this after its test runner returns.
session.record({
    "type": "test_passed",
    "summary": "pytest tests/test_login.py passed",
    "acceptance_id": "criterion-1",
    "tool": "pytest",
})
result = session.complete(lesson="The login integration test now passes.")
```

`tool_succeeded`, `tool_failed`, `test_passed`, `test_failed`,
`verification_passed`, `verification_failed`, and `note` are supported.  The
session rejects malformed, unknown, and out-of-order events; it derives the
final result from declared acceptance evidence rather than trusting a model to
claim success.

## Workflow 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.
- a durable workflow controller for task contracts, six-axis difficulty,
  PlanIR admission, active steps, results, explicit replan, and feedback
  closure.

Runtime does not provide natural-language interpretation, model selection,
provider SDKs, tool execution, parallel scheduling, durable conversation
memory, or an HTTP service. The optional planner can propose plans but cannot
approve or execute them.

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