Metadata-Version: 2.4
Name: ocl-plan
Version: 0.1.0
Summary: OCL-PLAN+++ — Distributional Orientational Planning with Shift Field, Ω Observation, and Mean-Field Comparison
Author: OCL-PLAN Contributors
License: MIT
Project-URL: Homepage, https://github.com/your-org/ocl-plan
Project-URL: Repository, https://github.com/your-org/ocl-plan
Project-URL: Bug Tracker, https://github.com/your-org/ocl-plan/issues
Project-URL: Documentation, https://github.com/your-org/ocl-plan#readme
Keywords: planning,orientation,distributional,cognitive,ai,mean-field,game-theory,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pytest>=8.4.2
Requires-Dist: pytest-cov>=7.1.0
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Dynamic: license-file

# OCL-PLAN+++

**Distributional Orientational Planning** — Shift Field · Ω Observation · Mean-Field Comparison

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/ocl-plan.svg)](https://pypi.org/project/ocl-plan/)

OCL-PLAN+++ is a compact, dependency-light Python library and CLI for **distributional strategic planning**. It models action sequences as orientation vectors in a latent cognitive space, compares their mean-field Ω distributions, and returns cooperative/adversarial probabilities — all from a single numpy dependency.

---

## Why OCL-PLAN+++?

Most planning frameworks compare trajectories point-by-point. OCL-PLAN+++ instead:

- Represents each action sequence as a **distribution** over orientation vectors (via ensemble rollouts)
- Computes a **mean-field angular distance** between distributions rather than individual states
- Uses a **learnable shift field** (Gaussian prior) to soft-weight cognitive displacement
- Outputs an **adversarial/cooperative probability** in [0, 1] via a sigmoid gate

This makes it robust to noise, stochastic actions, and non-deterministic environments — well-suited for multi-agent reasoning, alignment research, and strategy comparison.

---

## Install

```bash
pip install ocl-plan
```

Or from source:

```bash
git clone https://github.com/your-org/ocl-plan
cd ocl-plan
pip install -e .
```

Optional YAML config support:

```bash
pip install "ocl-plan[yaml]"
```

---

## Quick Start

```bash
# Run the built-in paper demo (cooperate vs. defect)
ocl-plan demo

# Show per-step trajectory
ocl-plan demo --verbose --seed 42

# Generate a config file, edit it, then compare
ocl-plan init
ocl-plan compare --config ocl_config.json

# Print the mathematical summary
ocl-plan info
```

---

## CLI Reference

### `ocl-plan demo`

Run the canonical cooperate-vs-defect demo from the OCL-PLAN+++ paper.

```
ocl-plan demo [--seed INT] [--beta FLOAT] [--tau FLOAT] [--verbose] [--json]
```

| Flag | Default | Description |
|------|---------|-------------|
| `--seed` | `42` | Random seed for reproducibility |
| `--beta` | `5.0` | Sigmoid sharpness β |
| `--tau` | `1.0` | Cooperation threshold τ |
| `--verbose` | off | Print per-step proposition + uncertainty trajectory |
| `--json` | off | Dump raw JSON result to stdout |

---

### `ocl-plan compare`

Compare two action sequences from a JSON (or YAML) config file.

```
ocl-plan compare --config FILE [--seq-a a1,a2,...] [--seq-b b1,b2,...] \
                 [--seed INT] [--beta FLOAT] [--tau FLOAT] [--verbose] [--json]
```

`--seq-a` / `--seq-b` always override whatever is in the config's `compare` block, so one config file can drive many experiments.

---

### `ocl-plan init`

Write a ready-to-edit sample config file.

```
ocl-plan init [--output FILE] [--force]
```

---

### `ocl-plan info`

Print the mathematical foundation of OCL-PLAN+++.

---

## Config Format

```json
{
  "dim": 8,
  "rollouts": 8,
  "actions": {
    "cooperate": {
      "preconditions": ["at_meeting"],
      "effects": [{ "name": "trust_high", "polarity": 1 }],
      "base_vector": [1.0, 0.2, 0.0, 0.1, 0.0, 0.3, 0.0, 0.1],
      "noise": 0.0
    },
    "defect": {
      "preconditions": ["at_meeting"],
      "effects": [{ "name": "trust_high", "polarity": -1 }],
      "base_vector": [-1.0, 0.5, 0.2, 0.1, 0.0, 0.0, 0.3, 0.0],
      "noise": 0.0
    }
  },
  "initial_state": {
    "propositions": { "at_meeting": 1.0 },
    "h": "random"
  },
  "compare": {
    "seq_a": ["cooperate"],
    "seq_b": ["defect"]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `dim` | int | Dimensionality of orientation vectors |
| `rollouts` | int | Number of stochastic ensemble rollouts |
| `actions.<name>.base_vector` | float[] | Length must equal `dim` |
| `actions.<name>.noise` | float | Gaussian noise std added per step |
| `actions.<name>.preconditions` | string[] | Proposition names that must hold (truth > 0.6) |
| `actions.<name>.effects` | object[] | `{name, polarity}` — polarity `+1` reinforces, `-1` weakens |
| `initial_state.h` | `"random"` \| float[] | Initial latent state vector |
| `initial_state.Omega` | float[] | Optional; defaults to `h` |
| `compare.seq_a/seq_b` | string[] | Default sequences (overridable via CLI) |

---

## Python API

```python
import numpy as np
from ocl_plan_cli.core import (
    OCLPlanPlusPlus, OCLAction, Effect,
    CognitiveState, SituatedProposition, normalize,
)

engine = OCLPlanPlusPlus(dim=8, rollouts=16)

engine.actions = {
    "cooperate": OCLAction(
        "cooperate",
        preconditions=["at_meeting"],
        effects=[Effect("trust_high", +1)],
        base_vector=np.array([1.0, 0.2, 0.0, 0.1, 0.0, 0.3, 0.0, 0.1]),
    ),
    "defect": OCLAction(
        "defect",
        preconditions=["at_meeting"],
        effects=[Effect("trust_high", -1)],
        base_vector=np.array([-1.0, 0.5, 0.2, 0.1, 0.0, 0.0, 0.3, 0.0]),
    ),
}

h0 = normalize(np.random.randn(8))
state = CognitiveState(
    propositions={"at_meeting": SituatedProposition("at_meeting", 1.0)},
    h=h0,
    Omega=h0.copy(),
)

result = engine.compare(state, ["cooperate"], ["defect"])
print(result)
# {
#   "orientation_distance": 0.41,
#   "adversarial_probability": 0.05,
#   "cooperative_probability": 0.95,
#   ...
# }
```

---

## Mathematical Foundation

$$P(\text{shift}) = \exp\!\left(-\frac{(\theta - \mu)^2}{2\sigma^2}\right)$$

$$\Omega = \text{norm}(W \cdot h)$$

$$d(A, B) = \angle(\mu_A,\, \mu_B), \quad \mu = \text{norm}\!\left(\mathbb{E}[\Omega]\right)$$

$$P_{\text{adv}} = \sigma\!\left(\beta\,(d - \tau)\right)$$

Where:
- **μ** is a learnable neutral prior (not hard-coded physics)
- **Ω** is an *observation* of latent state **h**, not a state variable
- **d(A, B)** is computed over the full ensemble of rollout trajectories
- **β** controls sharpness; **τ** is the cooperation/adversarial threshold

---

## Contributing

Pull requests are welcome. Please open an issue first for significant changes.

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Add or update tests in `tests/`
4. Run `pytest`
5. Open a PR

---

## License

[MIT](LICENSE) — free to use in research and commercial projects.
