mcp-cognitive-substrate 1.0.0__tar.gz

mcp_cognitive_substrate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JaysonAIOnline
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_cognitive_substrate-1.0.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mcp-cognitive-substrate
+Version: 1.0.0
+Summary: 28-layer cognitive substrate + cross-session ToT evolutionary memory + A2A tools for MCP agents
+License: MIT
+Project-URL: Homepage, https://github.com/JaysonAIOnline/mcp-cognitive-substrate
+Project-URL: Documentation, https://github.com/JaysonAIOnline/mcp-cognitive-substrate#readme
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Dynamic: license-file
+
+# mcp-cognitive-substrate
+
+A **28-layer cognitive substrate** with cross-session **Tree-of-Thoughts (ToT) evolutionary memory**, conditional self-telemetry, and **A2A tools** for MCP agents.
+
+Lets agents reason through a validated 28-layer substrate, evolve memory across sessions, and communicate with peer agents — all in one pip-installable package.
+
+## Features
+
+- **28-layer cognitive substrate with Pydantic validation** — `CognitiveSubstrate` validates reasoning through 6 families / 28 layers.
+- **Cross-session ToT evolutionary memory** — SQLite-backed tree-of-thoughts nodes + substrate history; pruned branches become lessons for future sessions.
+- **Robust stack-based JSON parser** — no regex; handles nested brackets, escaped strings, embedded code fences (`robust_slice` / `robust_json_slice`).
+- **Self-telemetry tool** — `get_cognitive_tree_state` returns active paths and pruned branches for a session.
+- **Post-execution storage loop** — `store_5key_telemetry` auto-saves compact 5-key telemetry (foundations, metacognition, defensive, resource, utility).
+- **7 reasoning paradigms** — deductive, inductive, abductive, analogical, causal, syllogistic, falsification.
+- **A2A tools** — list, discover, call, and orchestrate peer agents.
+- **MCP server** — exposes everything as tools via the `cognitive-substrate` CLI.
+
+## Install
+
+```bash
+pip install mcp-cognitive-substrate
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/JaysonAIOnline/mcp-cognitive-substrate.git
+cd mcp-cognitive-substrate
+pip install -e .[test]
+```
+
+Requires Python **>= 3.11**.
+
+## Quick Start
+
+```python
+from mcp_cognitive_substrate.substrate import CognitiveSubstrate
+from mcp_cognitive_substrate.memory import get_cognitive_tree_state, store_5key_telemetry
+
+substrate = CognitiveSubstrate()
+response = substrate.run("Your user prompt here")
+print(response["layers_applied"], "layers applied")
+print(response["substrate_verdict"])
+```
+
+## Usage
+
+### 28-layer substrate
+
+```python
+from mcp_cognitive_substrate import substrate
+
+# Layer count and schema
+print(substrate.layer_count())        # 28
+print(substrate.SUBSTRATE_SCHEMA)     # the full 6-family schema
+
+# Validate a prompt through the substrate
+result = substrate.CognitiveSubstrate(session_id="s1").run("deploy safely")
+print(result["substrate_verdict"])    # heuristic pruning verdict
+
+# Run a single paradigm
+from mcp_cognitive_substrate import run_paradigm
+print(run_paradigm("14_idempotency_side_effect_audit", {"evaluate_branch": True}))
+```
+
+### Cross-session ToT evolutionary memory
+
+```python
+from mcp_cognitive_substrate.memory import (
+    store_5key_telemetry,
+    get_cognitive_tree_state,
+    prune_failed_approach,
+)
+
+node_id = store_5key_telemetry(
+    session_id="session-a",
+    payload={
+        "foundations": {"premise_validation": "assuming deps", "state_hash": "h", "falsification_notes": "deps missing"},
+        "defensive": {"blast_radius": "unpredictable", "is_idempotent": True, "invariant_rule": "r"},
+        "resource": {"big_o": "o(n)", "latency_bottleneck": "none"},
+        "utility": {"load_summary": "pin versions to deploy", "checklist_verified": True},
+        "metacognition": {"self_critique": "c", "drift_pct": 0.1},
+    },
+    score_delta=-110.0,
+)
+prune_failed_approach(node_id)
+state = get_cognitive_tree_state("session-a", include_pruned=True)
+print(state["active_path_count"], state["pruned_branch_count"])
+```
+
+### Stack-based JSON parser
+
+```python
+from mcp_cognitive_substrate.memory import robust_slice, robust_json_slice
+
+cleaned, payload = robust_slice('prefix {"a": {"b": [1, 2]}, "c": "x"} suffix')
+# payload == {"a": {"b": [1, 2]}, "c": "x"}; cleaned == "prefix suffix"
+```
+
+### 7 reasoning paradigms + A2A
+
+```python
+from mcp_cognitive_substrate import reason, a2a_list, a2a_call, a2a_orchestrate
+
+print(reason("Solve X", reasoning_type="abductive", depth=3)["steps"])
+print(a2a_list())
+print(a2a_call("peer-agent", "hello"))
+print(a2a_orchestrate("hi", capability="memory"))
+```
+
+### As an MCP server
+
+```bash
+cognitive-substrate          # starts stdio MCP server
+cognitive-substrate --info   # prints package summary
+```
+
+All of the above — substrate paradigms, extraction/evaluation, memory store/recall, ToT lessons, tree-state telemetry, JSON parsing, reasoning plans, and A2A — are exposed as MCP tools.
+
+## Testing
+
+```bash
+pip install -e .[test]
+python -m pytest src/tests -q     # 16 tests
+```
+
+## License
+
+[MIT](LICENSE)

mcp_cognitive_substrate-1.0.0/README.md

@@ -0,0 +1,129 @@
+# mcp-cognitive-substrate
+
+A **28-layer cognitive substrate** with cross-session **Tree-of-Thoughts (ToT) evolutionary memory**, conditional self-telemetry, and **A2A tools** for MCP agents.
+
+Lets agents reason through a validated 28-layer substrate, evolve memory across sessions, and communicate with peer agents — all in one pip-installable package.
+
+## Features
+
+- **28-layer cognitive substrate with Pydantic validation** — `CognitiveSubstrate` validates reasoning through 6 families / 28 layers.
+- **Cross-session ToT evolutionary memory** — SQLite-backed tree-of-thoughts nodes + substrate history; pruned branches become lessons for future sessions.
+- **Robust stack-based JSON parser** — no regex; handles nested brackets, escaped strings, embedded code fences (`robust_slice` / `robust_json_slice`).
+- **Self-telemetry tool** — `get_cognitive_tree_state` returns active paths and pruned branches for a session.
+- **Post-execution storage loop** — `store_5key_telemetry` auto-saves compact 5-key telemetry (foundations, metacognition, defensive, resource, utility).
+- **7 reasoning paradigms** — deductive, inductive, abductive, analogical, causal, syllogistic, falsification.
+- **A2A tools** — list, discover, call, and orchestrate peer agents.
+- **MCP server** — exposes everything as tools via the `cognitive-substrate` CLI.
+
+## Install
+
+```bash
+pip install mcp-cognitive-substrate
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/JaysonAIOnline/mcp-cognitive-substrate.git
+cd mcp-cognitive-substrate
+pip install -e .[test]
+```
+
+Requires Python **>= 3.11**.
+
+## Quick Start
+
+```python
+from mcp_cognitive_substrate.substrate import CognitiveSubstrate
+from mcp_cognitive_substrate.memory import get_cognitive_tree_state, store_5key_telemetry
+
+substrate = CognitiveSubstrate()
+response = substrate.run("Your user prompt here")
+print(response["layers_applied"], "layers applied")
+print(response["substrate_verdict"])
+```
+
+## Usage
+
+### 28-layer substrate
+
+```python
+from mcp_cognitive_substrate import substrate
+
+# Layer count and schema
+print(substrate.layer_count())        # 28
+print(substrate.SUBSTRATE_SCHEMA)     # the full 6-family schema
+
+# Validate a prompt through the substrate
+result = substrate.CognitiveSubstrate(session_id="s1").run("deploy safely")
+print(result["substrate_verdict"])    # heuristic pruning verdict
+
+# Run a single paradigm
+from mcp_cognitive_substrate import run_paradigm
+print(run_paradigm("14_idempotency_side_effect_audit", {"evaluate_branch": True}))
+```
+
+### Cross-session ToT evolutionary memory
+
+```python
+from mcp_cognitive_substrate.memory import (
+    store_5key_telemetry,
+    get_cognitive_tree_state,
+    prune_failed_approach,
+)
+
+node_id = store_5key_telemetry(
+    session_id="session-a",
+    payload={
+        "foundations": {"premise_validation": "assuming deps", "state_hash": "h", "falsification_notes": "deps missing"},
+        "defensive": {"blast_radius": "unpredictable", "is_idempotent": True, "invariant_rule": "r"},
+        "resource": {"big_o": "o(n)", "latency_bottleneck": "none"},
+        "utility": {"load_summary": "pin versions to deploy", "checklist_verified": True},
+        "metacognition": {"self_critique": "c", "drift_pct": 0.1},
+    },
+    score_delta=-110.0,
+)
+prune_failed_approach(node_id)
+state = get_cognitive_tree_state("session-a", include_pruned=True)
+print(state["active_path_count"], state["pruned_branch_count"])
+```
+
+### Stack-based JSON parser
+
+```python
+from mcp_cognitive_substrate.memory import robust_slice, robust_json_slice
+
+cleaned, payload = robust_slice('prefix {"a": {"b": [1, 2]}, "c": "x"} suffix')
+# payload == {"a": {"b": [1, 2]}, "c": "x"}; cleaned == "prefix suffix"
+```
+
+### 7 reasoning paradigms + A2A
+
+```python
+from mcp_cognitive_substrate import reason, a2a_list, a2a_call, a2a_orchestrate
+
+print(reason("Solve X", reasoning_type="abductive", depth=3)["steps"])
+print(a2a_list())
+print(a2a_call("peer-agent", "hello"))
+print(a2a_orchestrate("hi", capability="memory"))
+```
+
+### As an MCP server
+
+```bash
+cognitive-substrate          # starts stdio MCP server
+cognitive-substrate --info   # prints package summary
+```
+
+All of the above — substrate paradigms, extraction/evaluation, memory store/recall, ToT lessons, tree-state telemetry, JSON parsing, reasoning plans, and A2A — are exposed as MCP tools.
+
+## Testing
+
+```bash
+pip install -e .[test]
+python -m pytest src/tests -q     # 16 tests
+```
+
+## License
+
+[MIT](LICENSE)

mcp_cognitive_substrate-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "mcp-cognitive-substrate"
+version = "1.0.0"
+description = "28-layer cognitive substrate + cross-session ToT evolutionary memory + A2A tools for MCP agents"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=2.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+cognitive-substrate = "mcp_cognitive_substrate.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/JaysonAIOnline/mcp-cognitive-substrate"
+Documentation = "https://github.com/JaysonAIOnline/mcp-cognitive-substrate#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mcp_cognitive_substrate*"]

mcp_cognitive_substrate-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_cognitive_substrate-1.0.0/src/mcp_cognitive_substrate/__init__.py

@@ -0,0 +1,66 @@
+"""mcp-cognitive-substrate.
+
+28-layer cognitive substrate + cross-session ToT evolutionary memory
++ A2A tools for MCP agents.
+"""
+
+__version__ = "1.0.0"
+
+from . import memory, substrate, tools
+from .memory import (
+    ToTMemory,
+    ensure_schema,
+    get_cognitive_tree_state,
+    prune_failed_approach,
+    recall,
+    robust_json_slice,
+    robust_slice,
+    store,
+    store_5key_telemetry,
+)
+from .substrate import (
+    PARADIGMS,
+    SUBSTRATE_SCHEMA,
+    CognitiveSubstrate,
+    evaluate_substrate,
+    extract_substrate,
+    run_paradigm,
+)
+from .tools import (
+    A2ARegistry,
+    REASONING_PARADIGMS,
+    a2a_call,
+    a2a_discover,
+    a2a_list,
+    a2a_orchestrate,
+    reason,
+)
+
+__all__ = [
+    "__version__",
+    "memory",
+    "substrate",
+    "tools",
+    "ToTMemory",
+    "ensure_schema",
+    "get_cognitive_tree_state",
+    "prune_failed_approach",
+    "recall",
+    "robust_json_slice",
+    "robust_slice",
+    "store",
+    "store_5key_telemetry",
+    "PARADIGMS",
+    "SUBSTRATE_SCHEMA",
+    "CognitiveSubstrate",
+    "evaluate_substrate",
+    "extract_substrate",
+    "run_paradigm",
+    "A2ARegistry",
+    "REASONING_PARADIGMS",
+    "a2a_call",
+    "a2a_discover",
+    "a2a_list",
+    "a2a_orchestrate",
+    "reason",
+]

mcp_cognitive_substrate-1.0.0/src/mcp_cognitive_substrate/cli.py

@@ -0,0 +1,146 @@
+"""MCP server entrypoint for mcp-cognitive-substrate.
+
+Run with::
+
+    cognitive-substrate
+
+or ``python -m mcp_cognitive_substrate.cli``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any, Dict, List
+
+from . import __version__, memory, substrate, tools
+
+try:  # mcp is optional at import time; CLI requires it
+    from mcp.server.fastmcp import FastMCP
+    _MCP_AVAILABLE = True
+except Exception:  # pragma: no cover - only when mcp is missing
+    _MCP_AVAILABLE = False
+
+
+def _make_server() -> Any:
+    mcp = FastMCP("cognitive-substrate")
+
+    # -- substrate tools -----------------------------------------------------
+    @mcp.tool()
+    def substrate_paradigms() -> Dict[str, Any]:
+        """Return the 28-layer cognitive substrate schema and layer count."""
+        return {
+            "layer_count": substrate.layer_count(),
+            "families": list(substrate.SUBSTRATE_SCHEMA.keys()),
+            "schema": substrate.SUBSTRATE_SCHEMA,
+        }
+
+    @mcp.tool()
+    def substrate_run_paradigm(paradigm_id: str, data: Dict[str, Any] = None) -> Dict[str, Any]:
+        """Run a single 28-layer paradigm against provided data."""
+        return substrate.run_paradigm(paradigm_id, data or {})
+
+    @mcp.tool()
+    def substrate_extract(raw_text: str) -> Dict[str, Any]:
+        """Extract the substrate JSON payload from raw text."""
+        substrate_dict, cleaned = substrate.extract_substrate(raw_text)
+        return {"substrate": substrate_dict, "cleaned": cleaned}
+
+    @mcp.tool()
+    def substrate_evaluate(payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Score a substrate instance. Returns (score_delta, is_pruned)."""
+        score_delta, is_pruned = substrate.evaluate_substrate(payload)
+        return {"score_delta": score_delta, "is_pruned": is_pruned, "accepted": is_pruned == 0}
+
+    # -- ToT memory tools -----------------------------------------------------
+    @mcp.tool()
+    def memory_store(content: str, topic: str = "general", tags: str = "", session_id: str = "default") -> Dict[str, Any]:
+        """Store a memory for cross-session recall."""
+        mid = memory.store(content, topic=topic, tags=tags, session_id=session_id)
+        return {"id": mid}
+
+    @mcp.tool()
+    def memory_recall(query: str, k: int = 8, session_id: str = "") -> Dict[str, Any]:
+        """Recall memories ranked by relevance."""
+        kw = {"k": k}
+        if session_id:
+            kw["session_id"] = session_id
+        return {"results": memory.recall(query, **kw)}
+
+    @mcp.tool()
+    def tot_historical_lessons(problem_context: str, max_lessons: int = 3) -> Dict[str, Any]:
+        """Pull pruned/penalized branches from past sessions as lessons."""
+        lessons = memory._get_default().historical_lessons(problem_context, max_lessons)
+        return {"lessons": lessons}
+
+    @mcp.tool()
+    def memory_store_5key_telemetry(session_id: str, payload: Dict[str, Any], score_delta: float = 0.0) -> Dict[str, Any]:
+        """Store 5-key compact substrate telemetry (post-execution storage loop)."""
+        node_id = memory.store_5key_telemetry(session_id, payload, score_delta)
+        return {"node_id": node_id}
+
+    @mcp.tool()
+    def memory_tree_state(session_id: str, include_pruned: bool = True) -> Dict[str, Any]:
+        """Get persistent cognitive-tree telemetry for a session."""
+        return memory.get_cognitive_tree_state(session_id, include_pruned)
+
+    @mcp.tool()
+    def json_parse_stack(raw: str) -> Dict[str, Any]:
+        """Parse the first top-level JSON object with the stack-based parser."""
+        cleaned, payload = memory.robust_slice(raw)
+        return {"cleaned": cleaned, "payload": payload}
+
+    # -- reasoning + A2A tools ------------------------------------------------
+    @mcp.tool()
+    def reasoning_paradigms() -> Dict[str, Any]:
+        """Return the 7 reasoning paradigms."""
+        return tools.REASONING_PARADIGMS
+
+    @mcp.tool()
+    def reason_plan(problem: str, reasoning_type: str = "deductive", depth: int = 5) -> Dict[str, Any]:
+        """Produce a structured reasoning plan for a problem."""
+        return tools.reason(problem, reasoning_type=reasoning_type, depth=depth)
+
+    @mcp.tool()
+    def a2a_list_agents() -> Dict[str, Any]:
+        """List registered peer agents."""
+        return {"agents": tools.a2a_list()}
+
+    @mcp.tool()
+    def a2a_call_agent(name: str, message: str) -> Dict[str, Any]:
+        """Call a peer agent by name."""
+        return tools.a2a_call(name, message)
+
+    @mcp.tool()
+    def a2a_orchestrate(capability: str, message: str, mode: str = "parallel") -> Dict[str, Any]:
+        """Fan out a message to agents with a given capability."""
+        return tools.a2a_orchestrate(message, capability=capability, mode=mode)
+
+    return mcp
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="cognitive-substrate")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--info", action="store_true", help="Print package summary and exit.")
+    args = parser.parse_args(argv)
+
+    if args.info:
+        print(f"mcp-cognitive-substrate v{__version__}")
+        print(f"28-layer substrate: {substrate.layer_count()} layers")
+        print(f"Reasoning paradigms: {list(tools.REASONING_PARADIGMS.keys())}")
+        print(f"Registered agents: {[a['name'] for a in tools.a2a_list()]}")
+        print("ToT memory db:", memory._DEFAULT_DB_PATH)
+        return 0
+
+    if not _MCP_AVAILABLE:
+        print("mcp is not installed. Run: pip install mcp", file=sys.stderr)
+        return 1
+
+    server = _make_server()
+    server.run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())