crystalplane 0.1.0__tar.gz

crystalplane-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: crystalplane
+Version: 0.1.0
+Summary: Hermetic, zero-dependency slim runtime client for Crystalplane / Crystalspace knowledge and skill crystals across non-Vanguard agent systems.
+Author-email: Enterprise Picard Engineering <engineering@picard.enterprise>
+License: Apache-2.0
+Keywords: crystalplane,crystalspace,agents,langchain,mcp,skills,knowledge,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == "all"
+Requires-Dist: crewai>=0.1.0; extra == "all"
+
+# Crystalplane Python Slim Runtime Client (`crystalplane`)
+
+A hermetic, zero-dependency Python client for connecting any AI agent system (LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI, Claude/MCP) to **Crystalplane** knowledge and skill crystals.
+
+## Features
+- **Zero External Dependencies**: Pure Python standard library (`urllib.request`, `hashlib`, `json`).
+- **Prompt Hydration**: Automatically resolves `~~shardID~~` markers in system prompts into verified authoritative skills.
+- **Dynamic Skill Assembly**: Call `/api/assemble` to compile composite skills within a specified token budget.
+- **Memory & Crystal Ingestion**: Ingest agent traces and learned workflows into durable SHA-256 microchain shards.
+- **Dual-Layer Caching**: In-memory LRU + optional persistent disk cache with SHA-256 node integrity verification.
+- **Universal MCP Bridge**: Run `python -m crystalplane.mcp_bridge` to expose Crystalplane tools to Claude Desktop, Cursor, or Zed.
+
+## Quickstart
+
+```python
+from crystalplane import CrystalClient
+
+# Automatically reads CRYSTAL_SERVER_URL and CRYSTAL_API_KEY from environment
+client = CrystalClient()
+
+# 1. Hydrate a prompt template with authoritative skill shards
+prompt = client.hydrate("""
+You are Picard's Chief Architect. Adhere to our platform invariants:
+~~sh_core_directive_mathematical_fidelity~~
+
+Task: {task}
+""", task="Verify the Reed-Solomon polynomial codec.")
+
+# 2. Search knowledge crystals
+results = client.search(query="distributed database locking", limit=5)
+
+# 3. Dynamic context assembly within token budget
+assembled = client.assemble(query="motor safety", max_tokens=2048)
+print(assembled.prompt_injection)
+```

crystalplane-0.1.0/README.md

@@ -0,0 +1,35 @@
+# Crystalplane Python Slim Runtime Client (`crystalplane`)
+
+A hermetic, zero-dependency Python client for connecting any AI agent system (LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI, Claude/MCP) to **Crystalplane** knowledge and skill crystals.
+
+## Features
+- **Zero External Dependencies**: Pure Python standard library (`urllib.request`, `hashlib`, `json`).
+- **Prompt Hydration**: Automatically resolves `~~shardID~~` markers in system prompts into verified authoritative skills.
+- **Dynamic Skill Assembly**: Call `/api/assemble` to compile composite skills within a specified token budget.
+- **Memory & Crystal Ingestion**: Ingest agent traces and learned workflows into durable SHA-256 microchain shards.
+- **Dual-Layer Caching**: In-memory LRU + optional persistent disk cache with SHA-256 node integrity verification.
+- **Universal MCP Bridge**: Run `python -m crystalplane.mcp_bridge` to expose Crystalplane tools to Claude Desktop, Cursor, or Zed.
+
+## Quickstart
+
+```python
+from crystalplane import CrystalClient
+
+# Automatically reads CRYSTAL_SERVER_URL and CRYSTAL_API_KEY from environment
+client = CrystalClient()
+
+# 1. Hydrate a prompt template with authoritative skill shards
+prompt = client.hydrate("""
+You are Picard's Chief Architect. Adhere to our platform invariants:
+~~sh_core_directive_mathematical_fidelity~~
+
+Task: {task}
+""", task="Verify the Reed-Solomon polynomial codec.")
+
+# 2. Search knowledge crystals
+results = client.search(query="distributed database locking", limit=5)
+
+# 3. Dynamic context assembly within token budget
+assembled = client.assemble(query="motor safety", max_tokens=2048)
+print(assembled.prompt_injection)
+```

crystalplane-0.1.0/crystalplane/__init__.py

@@ -0,0 +1,32 @@
+"""
+Crystalplane — Hermetic Slim Runtime Client for AI Agent Systems
+"""
+
+from crystalplane.client import (
+    AssembledCrystal,
+    CrystalClient,
+    CrystalClientError,
+    RegistrationResult,
+    Shard,
+)
+from crystalplane.cache import ShardCache
+from crystalplane.rate_limiter import RateLimiter
+from crystalplane.crawler import SkillCrawler
+from crystalplane.archive_crawler import ArchiveBookCrawler
+from crystalplane.research_lattice import ResearchLatticeEngine
+
+__version__ = "0.1.0"
+__all__ = [
+    "CrystalClient",
+    "CrystalClientError",
+    "Shard",
+    "AssembledCrystal",
+    "RegistrationResult",
+    "ShardCache",
+    "RateLimiter",
+    "SkillCrawler",
+    "ArchiveBookCrawler",
+    "ResearchLatticeEngine",
+    "__version__",
+]
+

crystalplane-0.1.0/crystalplane/__main__.py

@@ -0,0 +1,4 @@
+from crystalplane.cli import main
+
+if __name__ == "__main__":
+    main()

crystalplane-0.1.0/crystalplane/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""
+Crystalplane Adapters for Non-Vanguard Agent Frameworks
+"""

crystalplane-0.1.0/crystalplane/adapters/crewai.py

@@ -0,0 +1,40 @@
+"""
+Crystalplane — CrewAI Tool Adapter
+Provides native CrewAI BaseTool implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from crystalplane.client import CrystalClient
+
+
+def get_crewai_tools(client: CrystalClient) -> List[Any]:
+    """Returns CrewAI compatible BaseTool instances."""
+    try:
+        from crewai.tools import tool
+    except ImportError:
+        raise ImportError(
+            "CrewAI is not installed. Run `pip install crewai` or `pip install 'crystalplane[crewai]'`."
+        )
+
+    @tool("Search Crystalplane Knowledge")
+    def search_shards(query: str, domain: Optional[str] = None) -> str:
+        """Search Crystalplane for authoritative skills, directives, or knowledge shards by keyword."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_search", {"query": query, "domain": domain})
+
+    @tool("Get Shard by ID")
+    def get_shard(shard_id: str) -> str:
+        """Retrieve full authoritative markdown text of a specific Shard by its ID."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_get_shard", {"shard_id": shard_id})
+
+    @tool("Assemble Context Crystal")
+    def assemble_crystal(query: str, max_tokens: int = 2048) -> str:
+        """Dynamically assemble composite prompt injection context across shards within a token budget."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_assemble", {"query": query, "max_tokens": max_tokens})
+
+    return [search_shards, get_shard, assemble_crystal]

crystalplane-0.1.0/crystalplane/adapters/langchain.py

@@ -0,0 +1,51 @@
+"""
+Crystalplane — LangChain & LangGraph Adapter
+Provides native LangChain BaseTool and Retriever components.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from crystalplane.client import CrystalClient
+
+
+def get_crystal_tools(client: CrystalClient) -> List[Any]:
+    """Returns a list of LangChain BaseTool instances bound to the given CrystalClient."""
+    try:
+        from langchain_core.tools import tool
+    except ImportError:
+        raise ImportError(
+            "LangChain is not installed. Run `pip install langchain-core` or `pip install 'crystalplane[langchain]'`."
+        )
+
+    @tool
+    def crystal_search(query: str, domain: Optional[str] = None, limit: int = 5) -> str:
+        """Search Crystalplane for authoritative skill and knowledge shards by keywords."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_search", {"query": query, "domain": domain, "limit": limit})
+
+    @tool
+    def crystal_get_shard(shard_id: str) -> str:
+        """Retrieve the complete authoritative markdown content and metadata for a specific Shard by ID."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_get_shard", {"shard_id": shard_id})
+
+    @tool
+    def crystal_assemble(query: str, max_tokens: int = 2048) -> str:
+        """Assemble a Composite Skill Crystal within a token budget and return the compiled prompt injection."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_assemble", {"query": query, "max_tokens": max_tokens})
+
+    @tool
+    def crystal_crystallize(title: str, domain: str, raw_text: str, author_id: str = "agent:langchain") -> str:
+        """Persist a new skill, trace, or memory into a durable SHA-256 microchain Shard."""
+        from crystalplane.adapters.openai import execute_tool_call
+        return execute_tool_call(client, "crystal_crystallize", {
+            "title": title,
+            "domain": domain,
+            "raw_text": raw_text,
+            "author_id": author_id
+        })
+
+    return [crystal_search, crystal_get_shard, crystal_assemble, crystal_crystallize]

crystalplane-0.1.0/crystalplane/adapters/openai.py

@@ -0,0 +1,162 @@
+"""
+Crystalplane — OpenAI Function Calling & Swarm Adapter
+Provides standard OpenAI JSON tool schemas and automatic tool call execution.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+from crystalplane.client import CrystalClient
+
+
+def get_openai_tools() -> List[Dict[str, Any]]:
+    """Returns tool schemas compatible with `client.chat.completions.create(tools=...)`."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": "crystal_search",
+                "description": "Search the Crystalplane repository for authoritative skill and knowledge shards.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Keywords or semantic terms to search for (e.g. 'GAAP revenue recognition' or 'dead-time insertion')"
+                        },
+                        "domain": {
+                            "type": "string",
+                            "description": "Optional lab domain filter (e.g. 'software', 'research', 'hardware', 'accounting')"
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "Maximum number of shards to return (default: 5)"
+                        }
+                    },
+                    "required": ["query"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "crystal_get_shard",
+                "description": "Retrieve the complete authoritative markdown content and metadata for a specific Shard by ID.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "shard_id": {
+                            "type": "string",
+                            "description": "The canonical ID of the shard (e.g. 'sh_core_directive_mathematical_fidelity')"
+                        }
+                    },
+                    "required": ["shard_id"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "crystal_assemble",
+                "description": "Assemble a Composite Skill Crystal within a strict token budget and retrieve the compiled prompt injection.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query describing the domain skills needed"
+                        },
+                        "max_tokens": {
+                            "type": "integer",
+                            "description": "Maximum token budget (e.g. 2048)"
+                        }
+                    },
+                    "required": ["query"]
+                }
+            }
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "crystal_crystallize",
+                "description": "Persist a newly discovered skill, execution trace, or episodic memory into a durable SHA-256 microchain Shard.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "title": { "type": "string", "description": "Title of the knowledge or skill shard" },
+                        "domain": { "type": "string", "description": "Domain (e.g. 'software', 'research')" },
+                        "raw_text": { "type": "string", "description": "Markdown specification or documentation" },
+                        "author_id": { "type": "string", "description": "Agent handle or identifier" },
+                        "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional search tags" }
+                    },
+                    "required": ["title", "domain", "raw_text", "author_id"]
+                }
+            }
+        }
+    ]
+
+
+def execute_tool_call(client: CrystalClient, tool_name: str, arguments: str | Dict[str, Any]) -> str:
+    """Dispatches an OpenAI tool call and returns stringified JSON result."""
+    if isinstance(arguments, str):
+        try:
+            args = json.loads(arguments)
+        except Exception:
+            args = {}
+    else:
+        args = arguments
+
+    if tool_name == "crystal_search":
+        shards = client.search(
+            query=args.get("query", ""),
+            domain=args.get("domain"),
+            limit=args.get("limit", 5)
+        )
+        return json.dumps([
+            {
+                "id": s.id,
+                "title": s.title,
+                "domain": s.domain,
+                "tokens": s.token_count,
+                "preview": s.plaintext[:300] + ("..." if len(s.plaintext) > 300 else "")
+            }
+            for s in shards
+        ])
+
+    elif tool_name == "crystal_get_shard":
+        shard = client.get_shard(shard_id=args.get("shard_id", ""))
+        if not shard:
+            return json.dumps({"error": f"Shard '{args.get('shard_id')}' not found."})
+        return json.dumps(shard.to_dict())
+
+    elif tool_name == "crystal_assemble":
+        assembled = client.assemble(
+            query=args.get("query"),
+            max_tokens=args.get("max_tokens", 2048)
+        )
+        return json.dumps({
+            "title": assembled.title,
+            "crystalId": assembled.crystal_id,
+            "totalTokens": assembled.total_tokens,
+            "shardsCount": assembled.shards_count,
+            "promptInjection": assembled.prompt_injection
+        })
+
+    elif tool_name == "crystal_crystallize":
+        shard = client.crystallize(
+            title=args.get("title", "Untitled Shard"),
+            domain=args.get("domain", "software"),
+            raw_text=args.get("raw_text", ""),
+            author_id=args.get("author_id", "agent:openai"),
+            tags=args.get("tags")
+        )
+        return json.dumps({
+            "message": "Shard successfully crystallized and committed to blockchain.",
+            "shardId": shard.id,
+            "title": shard.title,
+            "tokens": shard.token_count
+        })
+
+    return json.dumps({"error": f"Unknown tool: {tool_name}"})