Metadata-Version: 2.4
Name: cordis-planner
Version: 0.4.0
Summary: Optional model-agnostic PlanIR proposal plugin for the CORDIS cognitive runtime.
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
Dynamic: license-file

# Cordis Planner

`cordis-planner` is an optional, provider-neutral proposal layer. It receives a
validated CORDIS task contract, difficulty profile, and Core Cognitive IR, then
asks an injected model callable for a JSON-only `cordis.plan.v1` proposal.

When Goal Mode has already run `cordis-socrates`, pass its
`cordis.boundary-review.v1` object as `boundary_review`. The proposal prompt
then carries the same scope, permission, capability, and evidence boundaries.

It cannot execute tools, approve actions, advance workflow state, or write
learning. `cordis-runtime` remains the authority for those transitions.

```text
CORDIS Runtime state -> CordisPlanner -> model callable -> PlanIR
                                                  |
                                                  v
                                    Runtime validates and controls execution
```

The package does not contain a model SDK. Integrations pass a callable such as
`lambda request: provider.generate(request["prompt"])`, which keeps provider
choice, credentials, and transport outside CORDIS.

## Plan Mode outcome

`CordisPlanMode` wraps one planning attempt in an explicit result:

- `plan_ready` -> the host submits the returned PlanIR to Runtime;
- `planner_failed` + `direct` -> only a Socrates review that marked planning
  non-required may let the host continue with its existing Goal Mode context;
- `planner_failed` + `repair_planner` -> the host must repair or retry the
  planner. It may not silently execute an unplanned high-complexity goal.
