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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: socratic-engine
-Version: 0.2.2
+Version: 0.2.4
 Summary: Externalized epistemic scaffolding for AI agents. Recursive boolean certification trees.
 License: Apache-2.0
 Keywords: socratic,epistemic,verification,certification,boolean-trees,trivalent-logic,mcp
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -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:** 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.
+**Status:** v0.2.3 published on PyPI — core engine, VSL tree parser, CLI, MCP bridge, multi-bridge (route canon_* to multiple providers by domain with health tracking + routing observability), VsmDocProvider, dialectical operator, pragmatic predicates, semantic simplification (NOT flattening, contradiction/tautology, dedup, absorption), short-circuit evaluation, tree DoS prevention (depth≤100, nodes≤10K), caching, rate limiting, CI (pytest 3.10–3.12 + coverage gate at 90%), 382-test suite + 46 adversarial tests (6 categories), benchmarks, 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.
 
 ---
 
@@ -647,7 +647,12 @@ 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 |
+| `socratic_canon_query` | (opt-in) query a data source through the registered bridge |
+| `socratic_canon_matches` | (opt-in, multi-bridge) check if records match expected values |
+| `socratic_canon_field_equals` | (opt-in, multi-bridge) check if a field equals expected value |
+| `socratic_canon_drift` | (opt-in, multi-bridge) detect declared vs observed drift |
+| `socratic_canon_domains` | (opt-in, multi-bridge) list all available domains |
+| `socratic_canon_providers` | (opt-in, multi-bridge) list all registered providers |
 
 The MCP layer is intentionally thin.
 
@@ -709,6 +714,45 @@ 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`.
 
+### Multi-bridge (new)
+
+For scenarios requiring certification across multiple data sources, the
+`MultiBridge` routes `canon_*` predicates to different providers by domain:
+
+```python
+from socratic_engine.multi_bridge import MultiBridge
+
+bridge = MultiBridge()
+bridge.add_provider("agent-state", vsm_provider, ["tasks", "sessions"])
+bridge.add_provider("infra-state", ssh_provider, ["services", "lxcs"])
+bridge.add_provider("vsm-docs", doc_provider, ["boot", "s1-operations"])
+bridge.register(eng)
+
+# Now the engine can certify across all domains:
+ev = eng.evaluate({"op": "AND", "children": [
+    {"predicate": "canon_query", "args": ["services", '{"name": "api"}']},
+    {"predicate": "canon_query", "args": ["boot", '{"name": "covenant"}']},
+]})
+```
+
+Or load from config:
+
+```bash
+SOCRATIC_BRIDGE_CONFIG=bridge_config.json python -m socratic_engine.mcp_server
+```
+
+**Provider health tracking**: each provider tracks consecutive failures.
+After 3 failures, the provider is marked unhealthy and `canon_providers`
+returns `UNKNOWN`. Failed queries return `UNKNOWN` (not FALSE) — a
+provider crash is indetermination, not falsity.
+
+**Routing observability**: every `canon_*` predicate includes routing
+info in its evidence: provider name, domain, latency_ms, record_count.
+This makes provider selection inspectable in the evaluation tree.
+
+See [`socratic_engine/multi_bridge.py`](./socratic_engine/multi_bridge.py) for
+the full API and config format.
+
 ---
 
 ## CLI
@@ -734,7 +778,7 @@ This makes the same engine usable from:
 
 ## Install
 
-### From PyPI (v0.2.2)
+### From PyPI (v0.2.3)
 
 ```bash
 pip install socratic-engine
@@ -765,7 +809,7 @@ python3 -m pytest tests/ -q
 The current repository snapshot passes:
 
 ```text
-189 passed
+382 passed
 ```
 
 at 100% statement coverage (CI gates at 90%; uncovered lines are
@@ -775,6 +819,47 @@ inline in the source).
 (includes integration tests with `state-canon`, available when that
 package is installed or reachable at `~/state-canon-mcp`)
 
+### Releases (GitHub ↔ PyPI sync)
+
+The release pipeline is automated via GitHub Actions
+([`.github/workflows/release.yml`](./.github/workflows/release.yml)),
+triggered by a tag. To ship a new version:
+
+```bash
+# 1. Bump the version in ALL four places (must match exactly):
+#    pyproject.toml  → version = "X.Y.Z"
+#    socratic_engine/__init__.py → __version__ = "X.Y.Z"
+#    socratic_engine/mcp_server.py → serverInfo version
+#    tests/test_mcp_server.py → the assert string
+# 2. Update README status + ROADMAP, commit, push to main
+git commit -am "release: vX.Y.Z — <what changed>"
+git push origin main
+
+# 3. Tag and push — the workflow verifies tag ↔ pyproject ↔ __init__
+#    match, runs the full suite, checks metadata (Apache-2.0 only),
+#    publishes to PyPI, and creates the GitHub Release.
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Prerequisites (one-time):
+- `PYPI_TOKEN` secret configured in
+  **GitHub → Settings → Secrets and variables → Actions**
+  (token from https://pypi.org/manage/account/token/)
+- workflow permissions: `contents: write` (set in the workflow file)
+
+The workflow FAILS loudly (it does not publish) if:
+- the tag version ≠ pyproject version ≠ `__init__.__version__`
+- the test suite or coverage gate fails
+- the wheel metadata contains anything other than Apache-2.0
+  (guard against the MIT-classifier regression that hit 0.2.2)
+
+Validated end-to-end 2026-08-19 (tag `v0.2.3` test run):
+sync guard ✓ → suite ✓ → build ✓ → metadata guard ✓ → publish reached
+PyPI with the token authenticated (server answered `400 File already
+exists` for the intentionally-republished version — a bad token would
+have answered 401/403, not 400).
+
 ---
 
 ## Repository layout
@@ -797,12 +882,18 @@ socratic-engine/
 │   ├── 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)
+│   ├── multi_bridge.py     # multi-provider routing (canon_* by domain)
+│   ├── bridge_statecanon.py # official state-canon bridge (opt-in)
+│   └── providers/
+│       ├── __init__.py
+│       └── vsm_doc.py      # VSM documentation filesystem provider
 └── tests/
     ├── test_engine.py
     ├── test_mcp_server.py
     ├── test_cli.py
     ├── test_bridge_statecanon.py
+    ├── test_multi_bridge.py
+    ├── test_vsm_doc.py
     └── test_state_canon_integration.py
 ```
 
@@ -1005,14 +1096,24 @@ Its purpose is narrower:
 - [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] published on PyPI (v0.2.0 → v0.2.3; bridge + ejemplos desde 0.2.2; license metadata Apache-only desde 0.2.3)
 - [x] official state-canon bridge + end-to-end examples (Claude Code, OpenCode)
+- [x] multi-bridge: route canon_* predicates to multiple providers by domain
+- [x] VsmDocProvider: VSM documentation as queryable records
+- [x] config-driven provider loading (bridge_config.json)
+- [x] provider health tracking (3-failure threshold → UNKNOWN)
+- [x] routing observability (provider, domain, latency, record count in evidence)
+- [x] semantic simplification: NOT flattening, contradiction/tautology, dedup, absorption
+- [x] short-circuit evaluation (AND stops at first FALSE, OR at first certified TRUE)
+- [x] tree DoS prevention (depth ≤ 100, nodes ≤ 10,000)
+- [x] 382-test suite + 46 adversarial tests (6 categories)
 
 ### v0.3.x — formal extension
 
-- [ ] paraconsistent logic
-- [ ] contextual / frame semantics
-- [ ] stakeholder participation graphs
+- [x] DIALECTICAL_AND — certified contradiction (exists since v0.1)
+- [ ] paraconsistent logic (full: beyond pairwise contradiction)
+- [ ] contextual / frame semantics (hermeneutica: meaning from context)
+- [ ] stakeholder participation graphs (discursive ethics)
 - [ ] formal VSM → Socratic Engine derivation
 
 The roadmap is intentionally open: the next features should be driven by failures observed in the experimental programme, not by feature accumulation.

{socratic_engine-0.2.2 → socratic_engine-0.2.4}/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:** 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.
+**Status:** v0.2.3 published on PyPI — core engine, VSL tree parser, CLI, MCP bridge, multi-bridge (route canon_* to multiple providers by domain with health tracking + routing observability), VsmDocProvider, dialectical operator, pragmatic predicates, semantic simplification (NOT flattening, contradiction/tautology, dedup, absorption), short-circuit evaluation, tree DoS prevention (depth≤100, nodes≤10K), caching, rate limiting, CI (pytest 3.10–3.12 + coverage gate at 90%), 382-test suite + 46 adversarial tests (6 categories), benchmarks, 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.
 
 ---
 
@@ -623,7 +623,12 @@ 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 |
+| `socratic_canon_query` | (opt-in) query a data source through the registered bridge |
+| `socratic_canon_matches` | (opt-in, multi-bridge) check if records match expected values |
+| `socratic_canon_field_equals` | (opt-in, multi-bridge) check if a field equals expected value |
+| `socratic_canon_drift` | (opt-in, multi-bridge) detect declared vs observed drift |
+| `socratic_canon_domains` | (opt-in, multi-bridge) list all available domains |
+| `socratic_canon_providers` | (opt-in, multi-bridge) list all registered providers |
 
 The MCP layer is intentionally thin.
 
@@ -685,6 +690,45 @@ 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`.
 
+### Multi-bridge (new)
+
+For scenarios requiring certification across multiple data sources, the
+`MultiBridge` routes `canon_*` predicates to different providers by domain:
+
+```python
+from socratic_engine.multi_bridge import MultiBridge
+
+bridge = MultiBridge()
+bridge.add_provider("agent-state", vsm_provider, ["tasks", "sessions"])
+bridge.add_provider("infra-state", ssh_provider, ["services", "lxcs"])
+bridge.add_provider("vsm-docs", doc_provider, ["boot", "s1-operations"])
+bridge.register(eng)
+
+# Now the engine can certify across all domains:
+ev = eng.evaluate({"op": "AND", "children": [
+    {"predicate": "canon_query", "args": ["services", '{"name": "api"}']},
+    {"predicate": "canon_query", "args": ["boot", '{"name": "covenant"}']},
+]})
+```
+
+Or load from config:
+
+```bash
+SOCRATIC_BRIDGE_CONFIG=bridge_config.json python -m socratic_engine.mcp_server
+```
+
+**Provider health tracking**: each provider tracks consecutive failures.
+After 3 failures, the provider is marked unhealthy and `canon_providers`
+returns `UNKNOWN`. Failed queries return `UNKNOWN` (not FALSE) — a
+provider crash is indetermination, not falsity.
+
+**Routing observability**: every `canon_*` predicate includes routing
+info in its evidence: provider name, domain, latency_ms, record_count.
+This makes provider selection inspectable in the evaluation tree.
+
+See [`socratic_engine/multi_bridge.py`](./socratic_engine/multi_bridge.py) for
+the full API and config format.
+
 ---
 
 ## CLI
@@ -710,7 +754,7 @@ This makes the same engine usable from:
 
 ## Install
 
-### From PyPI (v0.2.2)
+### From PyPI (v0.2.3)
 
 ```bash
 pip install socratic-engine
@@ -741,7 +785,7 @@ python3 -m pytest tests/ -q
 The current repository snapshot passes:
 
 ```text
-189 passed
+382 passed
 ```
 
 at 100% statement coverage (CI gates at 90%; uncovered lines are
@@ -751,6 +795,47 @@ inline in the source).
 (includes integration tests with `state-canon`, available when that
 package is installed or reachable at `~/state-canon-mcp`)
 
+### Releases (GitHub ↔ PyPI sync)
+
+The release pipeline is automated via GitHub Actions
+([`.github/workflows/release.yml`](./.github/workflows/release.yml)),
+triggered by a tag. To ship a new version:
+
+```bash
+# 1. Bump the version in ALL four places (must match exactly):
+#    pyproject.toml  → version = "X.Y.Z"
+#    socratic_engine/__init__.py → __version__ = "X.Y.Z"
+#    socratic_engine/mcp_server.py → serverInfo version
+#    tests/test_mcp_server.py → the assert string
+# 2. Update README status + ROADMAP, commit, push to main
+git commit -am "release: vX.Y.Z — <what changed>"
+git push origin main
+
+# 3. Tag and push — the workflow verifies tag ↔ pyproject ↔ __init__
+#    match, runs the full suite, checks metadata (Apache-2.0 only),
+#    publishes to PyPI, and creates the GitHub Release.
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Prerequisites (one-time):
+- `PYPI_TOKEN` secret configured in
+  **GitHub → Settings → Secrets and variables → Actions**
+  (token from https://pypi.org/manage/account/token/)
+- workflow permissions: `contents: write` (set in the workflow file)
+
+The workflow FAILS loudly (it does not publish) if:
+- the tag version ≠ pyproject version ≠ `__init__.__version__`
+- the test suite or coverage gate fails
+- the wheel metadata contains anything other than Apache-2.0
+  (guard against the MIT-classifier regression that hit 0.2.2)
+
+Validated end-to-end 2026-08-19 (tag `v0.2.3` test run):
+sync guard ✓ → suite ✓ → build ✓ → metadata guard ✓ → publish reached
+PyPI with the token authenticated (server answered `400 File already
+exists` for the intentionally-republished version — a bad token would
+have answered 401/403, not 400).
+
 ---
 
 ## Repository layout
@@ -773,12 +858,18 @@ socratic-engine/
 │   ├── 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)
+│   ├── multi_bridge.py     # multi-provider routing (canon_* by domain)
+│   ├── bridge_statecanon.py # official state-canon bridge (opt-in)
+│   └── providers/
+│       ├── __init__.py
+│       └── vsm_doc.py      # VSM documentation filesystem provider
 └── tests/
     ├── test_engine.py
     ├── test_mcp_server.py
     ├── test_cli.py
     ├── test_bridge_statecanon.py
+    ├── test_multi_bridge.py
+    ├── test_vsm_doc.py
     └── test_state_canon_integration.py
 ```
 
@@ -981,14 +1072,24 @@ Its purpose is narrower:
 - [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] published on PyPI (v0.2.0 → v0.2.3; bridge + ejemplos desde 0.2.2; license metadata Apache-only desde 0.2.3)
 - [x] official state-canon bridge + end-to-end examples (Claude Code, OpenCode)
+- [x] multi-bridge: route canon_* predicates to multiple providers by domain
+- [x] VsmDocProvider: VSM documentation as queryable records
+- [x] config-driven provider loading (bridge_config.json)
+- [x] provider health tracking (3-failure threshold → UNKNOWN)
+- [x] routing observability (provider, domain, latency, record count in evidence)
+- [x] semantic simplification: NOT flattening, contradiction/tautology, dedup, absorption
+- [x] short-circuit evaluation (AND stops at first FALSE, OR at first certified TRUE)
+- [x] tree DoS prevention (depth ≤ 100, nodes ≤ 10,000)
+- [x] 382-test suite + 46 adversarial tests (6 categories)
 
 ### v0.3.x — formal extension
 
-- [ ] paraconsistent logic
-- [ ] contextual / frame semantics
-- [ ] stakeholder participation graphs
+- [x] DIALECTICAL_AND — certified contradiction (exists since v0.1)
+- [ ] paraconsistent logic (full: beyond pairwise contradiction)
+- [ ] contextual / frame semantics (hermeneutica: meaning from context)
+- [ ] stakeholder participation graphs (discursive ethics)
 - [ ] formal VSM → Socratic Engine derivation
 
 The roadmap is intentionally open: the next features should be driven by failures observed in the experimental programme, not by feature accumulation.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "socratic-engine"
-version = "0.2.2"
+version = "0.2.4"
 description = "Externalized epistemic scaffolding for AI agents. Recursive boolean certification trees."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -32,7 +32,7 @@ socratic-engine = "socratic_engine.cli:main"
 socratic-engine-mcp = "socratic_engine.mcp_server:main"
 
 [tool.setuptools]
-packages = ["socratic_engine"]
+packages = ["socratic_engine", "socratic_engine.providers"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

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

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

{socratic_engine-0.2.2 → socratic_engine-0.2.4}/socratic_engine/engine.py

@@ -593,6 +593,47 @@ class SocraticEngine:
     # Evaluación de operadores lógicos
     # --------------------------------------------------------
 
+    def _evaluate_short_circuit(
+        self,
+        children_nodes: List[Any],
+        ctx: Dict[str, Any],
+        stop_on: Truth,
+    ) -> List[Evaluation]:
+        """Evaluate children lazily, stopping on a DECISIVE result.
+
+        For AND: stop on first FALSE (always decisive).
+        For OR:  stop on first certified TRUE (uncertified TRUE is not
+                 decisive — a later sibling may be certified).
+
+        Unevaluated children are recorded as UNKNOWN with source
+        'short_circuit'.  If we exhaust all children without a decisive
+        stop, returns full list (caller applies _apply_operator as usual).
+        """
+        children: List[Evaluation] = []
+        for child_node in children_nodes:
+            ev = self.evaluate(child_node, ctx)
+            children.append(ev)
+
+            if stop_on == Truth.FALSE:
+                # AND: FALSE is always decisive
+                if ev.truth == Truth.FALSE:
+                    for _ in children_nodes[len(children):]:
+                        children.append(Evaluation(
+                            truth=Truth.UNKNOWN, certified=False,
+                            source="short_circuit", context=ctx.copy(),
+                        ))
+                    break
+            elif stop_on == Truth.TRUE:
+                # OR: certified TRUE is decisive; uncertified is NOT
+                if ev.truth == Truth.TRUE and ev.certified:
+                    for _ in children_nodes[len(children):]:
+                        children.append(Evaluation(
+                            truth=Truth.UNKNOWN, certified=False,
+                            source="short_circuit", context=ctx.copy(),
+                        ))
+                    break
+        return children
+
     def _evaluate_operator(
         self,
         node: Dict[str, Any],
@@ -603,7 +644,16 @@ class SocraticEngine:
             raise ValueError(f"Operador desconocido: {op}")
 
         children_nodes = node.get("children", [])
-        children = [self.evaluate(child, ctx) for child in children_nodes]
+
+        # Short-circuit evaluation for AND/OR (semantic optimization)
+        if op == "AND":
+            children = self._evaluate_short_circuit(children_nodes, ctx,
+                                                    stop_on=Truth.FALSE)
+        elif op == "OR":
+            children = self._evaluate_short_circuit(children_nodes, ctx,
+                                                    stop_on=Truth.TRUE)
+        else:
+            children = [self.evaluate(child, ctx) for child in children_nodes]
 
         truth = self._apply_operator(op, children)