socratic-engine 0.2.0__tar.gz → 0.2.2__tar.gz

{socratic_engine-0.2.0/socratic_engine.egg-info → socratic_engine-0.2.2}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: socratic-engine
-Version: 0.2.0
+Version: 0.2.2
 Summary: Externalized epistemic scaffolding for AI agents. Recursive boolean certification trees.
-License: MIT
+License: Apache-2.0
 Keywords: socratic,epistemic,verification,certification,boolean-trees,trivalent-logic,mcp
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -32,7 +32,7 @@ Dynamic: license-file
 
 The engine is deliberately small. It does not try to make an LLM "smarter". It gives the model a formal structure in which complex questioning can be proposed, executed recursively, inspected, and diagnosed **outside the model's token-generation loop**.
 
-**Status:** early / exploratory — the core engine, VSL tree parser, CLI, MCP bridge, and test suite are working. The broader claim — that externalizing recursive structure improves reliability on tasks that exceed a model's implicit recursive reasoning capacity — is an experimental hypothesis, not a proclamation.
+**Status:** v0.2.2 published on PyPI — core engine, VSL tree parser, CLI, MCP bridge, dialectical operator, pragmatic predicates, caching, rate limiting, CI (pytest 3.10–3.12 + coverage gate at 90%), benchmarks, a 189-test suite at 100% statement coverage, and the official state-canon bridge ([`bridge_statecanon.py`](./socratic_engine/bridge_statecanon.py)) with end-to-end examples are working. The broader claim — that externalizing recursive structure improves reliability on tasks that exceed a model's implicit recursive reasoning capacity — is an experimental hypothesis, not a proclamation.
 
 ---
 
@@ -83,6 +83,7 @@ At its core, the engine evaluates trees composed of:
 - `NOT`
 - `XOR`
 - `IMPLIES`
+- `DIALECTICAL_AND`
 - registered predicates
 - boolean literals
 
@@ -419,6 +420,7 @@ The engine implements:
 | `NOT` | invert one proposition | child must be certified |
 | `XOR` | exactly one true branch | children must be certified |
 | `IMPLIES` | antecedent → consequent | antecedent and consequent must be certified when relevant |
+| `DIALECTICAL_AND` | contradiction is not rejection — a certified TRUE/FALSE conflict yields `UNKNOWN` (certified), with thesis/antithesis in metadata | in conflict: all children certified (the contradiction itself is a fact); without conflict: all children certified |
 
 The distinction matters for diagnosis.
 
@@ -602,7 +604,7 @@ The model is therefore not trusted to produce executable logic merely because th
 
 ## Built-in predicates
 
-The engine currently ships with deterministic predicates for structural classification:
+The engine currently ships with deterministic predicates for structural classification and pragmatic behaviour:
 
 | Predicate | Question | Missing subject |
 |---|---|---|
@@ -612,9 +614,14 @@ The engine currently ships with deterministic predicates for structural classifi
 | `type_has` | does TYPE contain a token? | `UNKNOWN` |
 | `doc_has_status` | does a document declare a status? | evaluated from document |
 | `ctx_has` | does context contain a key/value? | `UNKNOWN` |
+| `trend_up` | is a time series growing sustainably (min_delta, noise guard)? | `UNKNOWN` |
+| `trend_down` | is a time series falling sustainably (min_delta, noise guard)? | `UNKNOWN` |
+| `feedback_loop` | does a topology have a closed cycle (length ≥ 2) through target? | `UNKNOWN` |
 
 Registering custom predicates is the intended extension point.
 
+Costly predicates can be wrapped with `@cached(ttl=...)` — hits are marked `metadata.cached=True` (historical evidence, not a fresh measurement), `UNKNOWN` is never cached, and `engine.cache.clear()` forces re-verification.
+
 ---
 
 ## MCP bridge
@@ -640,13 +647,70 @@ The current bridge exposes:
 | `socratic_build` | validate a proposed reasoning tree |
 | `socratic_evaluate` | execute a tree against context |
 | `socratic_diagnose` | return inverse failure traces |
+| `socratic_canon_query` | (opt-in) query state-canon through the registered bridge |
 
 The MCP layer is intentionally thin.
 
+It includes a per-tool sliding-window rate limiter (`SOCRATIC_MCP_RATE_LIMIT`, default 100 calls / `SOCRATIC_MCP_RATE_WINDOW`, default 60s): a rate-limited call returns error `-32029` with `retry_after_s` — a transient signal, not a rejection.
+
 The reasoning contract remains in the engine.
 
 ---
 
+## Bridge to `state-canon` (official)
+
+The official integration between the engine and **state-canon** lives in
+[`socratic_engine/bridge_statecanon.py`](./socratic_engine/bridge_statecanon.py).
+
+**Division of labor** (from the "Relationship to `state-canon`" section):
+
+> **state-canon grounds the agent in what is observed.**
+> **socratic-engine constrains how claims about that state are evaluated.**
+
+The bridge registers four predicates on any `SocraticEngine`, all prefixed
+`canon_` — they query the provider (the reconciled ground truth, *observed*)
+and convert the result into certified evidence:
+
+| Predicate | Question it answers |
+|---|---|
+| `canon_query(domain, filter)` | Is there at least one record matching the filter? |
+| `canon_matches(domain, filter, expected)` | Do the records match the expected fields exactly? |
+| `canon_field_equals(domain, filter, field, expected)` | Does a specific field equal the expected value? |
+| `canon_drift(domain, filter, declared_field, observed_field)` | Have declared and observed drifted apart? |
+
+`filter` and `expected` accept either a JSON string or a Python dict.
+
+Semantics follow the engine's epistemology (R9 — no silent concession):
+
+- **TRUE / FALSE** are returned **certified** (structural evidence exists).
+- **UNKNOWN** is returned **uncertified** when there is no evidence — no
+  records, an unknown filter field, a missing field, or an unparseable
+  filter. No inventing, no silent routing to `else_home`.
+
+```python
+from socratic_engine import SocraticEngine
+from socratic_engine.bridge_statecanon import StateCanonBridge
+
+eng = SocraticEngine()
+bridge = StateCanonBridge(eng, provider)   # provider: state_canon.StateProvider
+
+ev = eng.evaluate({"op": "DIALECTICAL_AND", "children": [
+    {"predicate": "canon_field_equals",
+     "args": ["services", '{"name": "api"}', "declared_active", True]},
+    {"predicate": "canon_field_equals",
+     "args": ["services", '{"name": "api"}', "observed_active", True]},
+]})
+# declared TRUE, observed FALSE → certified conflict → UNKNOWN certified,
+# with metadata.thesis / metadata.antithesis — the dialectical operator
+# turns the drift into productive indetermination, not a false binary.
+```
+
+The MCP server accepts an optional `provider` (opt-in, R6): when set, the
+`canon_*` predicates are registered and `socratic_canon_query` appears in
+`tools/list`.
+
+---
+
 ## CLI
 
 Evaluate a JSON tree directly:
@@ -670,7 +734,17 @@ This makes the same engine usable from:
 
 ## Install
 
-> **Note:** the package is not published to PyPI yet. Install from source for now.
+### From PyPI (v0.2.2)
+
+```bash
+pip install socratic-engine
+```
+
+### With MCP support
+
+```bash
+pip install "socratic-engine[mcp]"
+```
 
 ### From source
 
@@ -682,12 +756,6 @@ python3 -m venv .venv
 .venv/bin/python -m pip install -e .
 ```
 
-### With MCP support
-
-```bash
-.venv/bin/python -m pip install -e ".[mcp]"
-```
-
 ### Run the tests
 
 ```bash
@@ -697,9 +765,16 @@ python3 -m pytest tests/ -q
 The current repository snapshot passes:
 
 ```text
-16 passed
+189 passed
 ```
 
+at 100% statement coverage (CI gates at 90%; uncovered lines are
+documented `# pragma: no cover` defensive branches — see the rationale
+inline in the source).
+
+(includes integration tests with `state-canon`, available when that
+package is installed or reachable at `~/state-canon-mcp`)
+
 ---
 
 ## Repository layout
@@ -709,18 +784,26 @@ socratic-engine/
 ├── README.md
 ├── ROADMAP.md
 ├── pyproject.toml
-├── examples/
-│   └── quickstart.py
+├── LICENSE
+├── benchmarks/
+│   └── benchmark.py        # deep/wide trees, cache speedup, diagnose
 ├── docs/
-│   └── ONTOLOGY.md
+│   ├── ONTOLOGY.md         # epistemic model
+│   ├── ARCHITECTURE.md     # how it fits together (code-faithful)
+│   └── EXAMPLES.md         # executable use cases
 ├── socratic_engine/
 │   ├── __init__.py
-│   ├── engine.py          # trivalent evaluator + certification + diagnosis
-│   ├── tree.py            # builder + VSL parser + tree routing
-│   ├── cli.py             # command-line interface
-│   └── mcp_server.py      # MCP / JSON-RPC bridge
+│   ├── engine.py           # trivalent evaluator + certification + diagnosis
+│   ├── tree.py             # builder + VSL parser + tree routing
+│   ├── cli.py              # command-line interface
+│   ├── mcp_server.py       # MCP / JSON-RPC bridge + rate limiter
+│   └── bridge_statecanon.py # official state-canon bridge (opt-in)
 └── tests/
-    └── test_engine.py
+    ├── test_engine.py
+    ├── test_mcp_server.py
+    ├── test_cli.py
+    ├── test_bridge_statecanon.py
+    └── test_state_canon_integration.py
 ```
 
 ---
@@ -914,14 +997,16 @@ Its purpose is narrower:
 
 ### v0.2.x — maturation
 
-- [ ] CI workflow
-- [ ] coverage reporting
-- [ ] integration tests with `state-canon`
-- [ ] performance benchmarks
-- [ ] richer examples and architecture documentation
-- [ ] dialectical operator for legitimate contradictions
-- [ ] temporal / pragmatic predicates
-- [ ] caching and rate limiting for expensive predicates
+- [x] CI workflow (pytest 3.10–3.12 + coverage + CLI smoke + MCP job)
+- [x] coverage > 90% (now 100%; CI gates at 90%)
+- [x] integration tests with `state-canon`
+- [x] performance benchmarks
+- [x] richer examples and architecture documentation
+- [x] dialectical operator for legitimate contradictions
+- [x] temporal / pragmatic predicates
+- [x] caching and rate limiting for expensive predicates
+- [x] published on PyPI (v0.2.0 → v0.2.2; bridge + ejemplos incluidos desde 0.2.2)
+- [x] official state-canon bridge + end-to-end examples (Claude Code, OpenCode)
 
 ### v0.3.x — formal extension
 
@@ -937,8 +1022,10 @@ The roadmap is intentionally open: the next features should be driven by failure
 ## Going deeper
 
 - **[docs/ONTOLOGY.md](./docs/ONTOLOGY.md)** — the epistemic model: truth, certification, UNKNOWN, operator semantics, and the LLM boundary.
-- **[ROADMAP.md](./ROADMAP.md)** — current development programme.
-- **[examples/quickstart.py](./examples/quickstart.py)** — three concrete cases: certified evidence, uncertified LLM judgment, and inverse diagnosis.
+- **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — how the modules fit together, written against the code.
+- **[docs/EXAMPLES.md](./docs/EXAMPLES.md)** — executable use cases: classification, deploy gates, diagnosis, dialectics, caching, rate limiting.
+- **[ROADMAP.md](./ROADMAP.md)** — current development programme (tracked as [issue #1](https://github.com/rm-w3kufe/socratic-engine/issues/1)).
+- **[benchmarks/benchmark.py](./benchmarks/benchmark.py)** — performance numbers (deep/wide trees, cache speedup, diagnose).
 - **[tests/](./tests/)** — executable specification of the current semantics.
 
 ---

{socratic_engine-0.2.0 → socratic_engine-0.2.2}/README.md

@@ -8,7 +8,7 @@
 
 The engine is deliberately small. It does not try to make an LLM "smarter". It gives the model a formal structure in which complex questioning can be proposed, executed recursively, inspected, and diagnosed **outside the model's token-generation loop**.
 
-**Status:** early / exploratory — the core engine, VSL tree parser, CLI, MCP bridge, and test suite are working. The broader claim — that externalizing recursive structure improves reliability on tasks that exceed a model's implicit recursive reasoning capacity — is an experimental hypothesis, not a proclamation.
+**Status:** v0.2.2 published on PyPI — core engine, VSL tree parser, CLI, MCP bridge, dialectical operator, pragmatic predicates, caching, rate limiting, CI (pytest 3.10–3.12 + coverage gate at 90%), benchmarks, a 189-test suite at 100% statement coverage, and the official state-canon bridge ([`bridge_statecanon.py`](./socratic_engine/bridge_statecanon.py)) with end-to-end examples are working. The broader claim — that externalizing recursive structure improves reliability on tasks that exceed a model's implicit recursive reasoning capacity — is an experimental hypothesis, not a proclamation.
 
 ---
 
@@ -59,6 +59,7 @@ At its core, the engine evaluates trees composed of:
 - `NOT`
 - `XOR`
 - `IMPLIES`
+- `DIALECTICAL_AND`
 - registered predicates
 - boolean literals
 
@@ -395,6 +396,7 @@ The engine implements:
 | `NOT` | invert one proposition | child must be certified |
 | `XOR` | exactly one true branch | children must be certified |
 | `IMPLIES` | antecedent → consequent | antecedent and consequent must be certified when relevant |
+| `DIALECTICAL_AND` | contradiction is not rejection — a certified TRUE/FALSE conflict yields `UNKNOWN` (certified), with thesis/antithesis in metadata | in conflict: all children certified (the contradiction itself is a fact); without conflict: all children certified |
 
 The distinction matters for diagnosis.
 
@@ -578,7 +580,7 @@ The model is therefore not trusted to produce executable logic merely because th
 
 ## Built-in predicates
 
-The engine currently ships with deterministic predicates for structural classification:
+The engine currently ships with deterministic predicates for structural classification and pragmatic behaviour:
 
 | Predicate | Question | Missing subject |
 |---|---|---|
@@ -588,9 +590,14 @@ The engine currently ships with deterministic predicates for structural classifi
 | `type_has` | does TYPE contain a token? | `UNKNOWN` |
 | `doc_has_status` | does a document declare a status? | evaluated from document |
 | `ctx_has` | does context contain a key/value? | `UNKNOWN` |
+| `trend_up` | is a time series growing sustainably (min_delta, noise guard)? | `UNKNOWN` |
+| `trend_down` | is a time series falling sustainably (min_delta, noise guard)? | `UNKNOWN` |
+| `feedback_loop` | does a topology have a closed cycle (length ≥ 2) through target? | `UNKNOWN` |
 
 Registering custom predicates is the intended extension point.
 
+Costly predicates can be wrapped with `@cached(ttl=...)` — hits are marked `metadata.cached=True` (historical evidence, not a fresh measurement), `UNKNOWN` is never cached, and `engine.cache.clear()` forces re-verification.
+
 ---
 
 ## MCP bridge
@@ -616,13 +623,70 @@ The current bridge exposes:
 | `socratic_build` | validate a proposed reasoning tree |
 | `socratic_evaluate` | execute a tree against context |
 | `socratic_diagnose` | return inverse failure traces |
+| `socratic_canon_query` | (opt-in) query state-canon through the registered bridge |
 
 The MCP layer is intentionally thin.
 
+It includes a per-tool sliding-window rate limiter (`SOCRATIC_MCP_RATE_LIMIT`, default 100 calls / `SOCRATIC_MCP_RATE_WINDOW`, default 60s): a rate-limited call returns error `-32029` with `retry_after_s` — a transient signal, not a rejection.
+
 The reasoning contract remains in the engine.
 
 ---
 
+## Bridge to `state-canon` (official)
+
+The official integration between the engine and **state-canon** lives in
+[`socratic_engine/bridge_statecanon.py`](./socratic_engine/bridge_statecanon.py).
+
+**Division of labor** (from the "Relationship to `state-canon`" section):
+
+> **state-canon grounds the agent in what is observed.**
+> **socratic-engine constrains how claims about that state are evaluated.**
+
+The bridge registers four predicates on any `SocraticEngine`, all prefixed
+`canon_` — they query the provider (the reconciled ground truth, *observed*)
+and convert the result into certified evidence:
+
+| Predicate | Question it answers |
+|---|---|
+| `canon_query(domain, filter)` | Is there at least one record matching the filter? |
+| `canon_matches(domain, filter, expected)` | Do the records match the expected fields exactly? |
+| `canon_field_equals(domain, filter, field, expected)` | Does a specific field equal the expected value? |
+| `canon_drift(domain, filter, declared_field, observed_field)` | Have declared and observed drifted apart? |
+
+`filter` and `expected` accept either a JSON string or a Python dict.
+
+Semantics follow the engine's epistemology (R9 — no silent concession):
+
+- **TRUE / FALSE** are returned **certified** (structural evidence exists).
+- **UNKNOWN** is returned **uncertified** when there is no evidence — no
+  records, an unknown filter field, a missing field, or an unparseable
+  filter. No inventing, no silent routing to `else_home`.
+
+```python
+from socratic_engine import SocraticEngine
+from socratic_engine.bridge_statecanon import StateCanonBridge
+
+eng = SocraticEngine()
+bridge = StateCanonBridge(eng, provider)   # provider: state_canon.StateProvider
+
+ev = eng.evaluate({"op": "DIALECTICAL_AND", "children": [
+    {"predicate": "canon_field_equals",
+     "args": ["services", '{"name": "api"}', "declared_active", True]},
+    {"predicate": "canon_field_equals",
+     "args": ["services", '{"name": "api"}', "observed_active", True]},
+]})
+# declared TRUE, observed FALSE → certified conflict → UNKNOWN certified,
+# with metadata.thesis / metadata.antithesis — the dialectical operator
+# turns the drift into productive indetermination, not a false binary.
+```
+
+The MCP server accepts an optional `provider` (opt-in, R6): when set, the
+`canon_*` predicates are registered and `socratic_canon_query` appears in
+`tools/list`.
+
+---
+
 ## CLI
 
 Evaluate a JSON tree directly:
@@ -646,7 +710,17 @@ This makes the same engine usable from:
 
 ## Install
 
-> **Note:** the package is not published to PyPI yet. Install from source for now.
+### From PyPI (v0.2.2)
+
+```bash
+pip install socratic-engine
+```
+
+### With MCP support
+
+```bash
+pip install "socratic-engine[mcp]"
+```
 
 ### From source
 
@@ -658,12 +732,6 @@ python3 -m venv .venv
 .venv/bin/python -m pip install -e .
 ```
 
-### With MCP support
-
-```bash
-.venv/bin/python -m pip install -e ".[mcp]"
-```
-
 ### Run the tests
 
 ```bash
@@ -673,9 +741,16 @@ python3 -m pytest tests/ -q
 The current repository snapshot passes:
 
 ```text
-16 passed
+189 passed
 ```
 
+at 100% statement coverage (CI gates at 90%; uncovered lines are
+documented `# pragma: no cover` defensive branches — see the rationale
+inline in the source).
+
+(includes integration tests with `state-canon`, available when that
+package is installed or reachable at `~/state-canon-mcp`)
+
 ---
 
 ## Repository layout
@@ -685,18 +760,26 @@ socratic-engine/
 ├── README.md
 ├── ROADMAP.md
 ├── pyproject.toml
-├── examples/
-│   └── quickstart.py
+├── LICENSE
+├── benchmarks/
+│   └── benchmark.py        # deep/wide trees, cache speedup, diagnose
 ├── docs/
-│   └── ONTOLOGY.md
+│   ├── ONTOLOGY.md         # epistemic model
+│   ├── ARCHITECTURE.md     # how it fits together (code-faithful)
+│   └── EXAMPLES.md         # executable use cases
 ├── socratic_engine/
 │   ├── __init__.py
-│   ├── engine.py          # trivalent evaluator + certification + diagnosis
-│   ├── tree.py            # builder + VSL parser + tree routing
-│   ├── cli.py             # command-line interface
-│   └── mcp_server.py      # MCP / JSON-RPC bridge
+│   ├── engine.py           # trivalent evaluator + certification + diagnosis
+│   ├── tree.py             # builder + VSL parser + tree routing
+│   ├── cli.py              # command-line interface
+│   ├── mcp_server.py       # MCP / JSON-RPC bridge + rate limiter
+│   └── bridge_statecanon.py # official state-canon bridge (opt-in)
 └── tests/
-    └── test_engine.py
+    ├── test_engine.py
+    ├── test_mcp_server.py
+    ├── test_cli.py
+    ├── test_bridge_statecanon.py
+    └── test_state_canon_integration.py
 ```
 
 ---
@@ -890,14 +973,16 @@ Its purpose is narrower:
 
 ### v0.2.x — maturation
 
-- [ ] CI workflow
-- [ ] coverage reporting
-- [ ] integration tests with `state-canon`
-- [ ] performance benchmarks
-- [ ] richer examples and architecture documentation
-- [ ] dialectical operator for legitimate contradictions
-- [ ] temporal / pragmatic predicates
-- [ ] caching and rate limiting for expensive predicates
+- [x] CI workflow (pytest 3.10–3.12 + coverage + CLI smoke + MCP job)
+- [x] coverage > 90% (now 100%; CI gates at 90%)
+- [x] integration tests with `state-canon`
+- [x] performance benchmarks
+- [x] richer examples and architecture documentation
+- [x] dialectical operator for legitimate contradictions
+- [x] temporal / pragmatic predicates
+- [x] caching and rate limiting for expensive predicates
+- [x] published on PyPI (v0.2.0 → v0.2.2; bridge + ejemplos incluidos desde 0.2.2)
+- [x] official state-canon bridge + end-to-end examples (Claude Code, OpenCode)
 
 ### v0.3.x — formal extension
 
@@ -913,8 +998,10 @@ The roadmap is intentionally open: the next features should be driven by failure
 ## Going deeper
 
 - **[docs/ONTOLOGY.md](./docs/ONTOLOGY.md)** — the epistemic model: truth, certification, UNKNOWN, operator semantics, and the LLM boundary.
-- **[ROADMAP.md](./ROADMAP.md)** — current development programme.
-- **[examples/quickstart.py](./examples/quickstart.py)** — three concrete cases: certified evidence, uncertified LLM judgment, and inverse diagnosis.
+- **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — how the modules fit together, written against the code.
+- **[docs/EXAMPLES.md](./docs/EXAMPLES.md)** — executable use cases: classification, deploy gates, diagnosis, dialectics, caching, rate limiting.
+- **[ROADMAP.md](./ROADMAP.md)** — current development programme (tracked as [issue #1](https://github.com/rm-w3kufe/socratic-engine/issues/1)).
+- **[benchmarks/benchmark.py](./benchmarks/benchmark.py)** — performance numbers (deep/wide trees, cache speedup, diagnose).
 - **[tests/](./tests/)** — executable specification of the current semantics.
 
 ---

{socratic_engine-0.2.0 → socratic_engine-0.2.2}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "socratic-engine"
-version = "0.2.0"
+version = "0.2.2"
 description = "Externalized epistemic scaffolding for AI agents. Recursive boolean certification trees."
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "MIT" }
+license = { text = "Apache-2.0" }
 keywords = ["socratic", "epistemic", "verification", "certification", "boolean-trees", "trivalent-logic", "mcp"]
 classifiers = [
     "Development Status :: 3 - Alpha",

{socratic_engine-0.2.0 → socratic_engine-0.2.2}/socratic_engine/__init__.py

@@ -56,4 +56,4 @@ __all__ = [
     "tree_home",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"