ocl-plan 0.1.0

OCL-PLAN+++ — Distributional Orientational Planning with Shift Field, Ω Observation, and Mean-Field Comparison

OCL-PLAN+++

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

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

pip install ocl-plan

Or from source:

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

Optional YAML config support:

pip install "ocl-plan[yaml]"

---

Quick Start

# 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

{
  "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

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 — free to use in research and commercial projects.