hyperstack-langgraph 1.0.0__py3-none-any.whl

hyperstack_langgraph/__init__.py

@@ -0,0 +1,289 @@
+"""
+HyperStack LangGraph Integration
+Knowledge graph memory for LangGraph agents.
+"""
+
+import os
+import json
+import urllib.request
+import urllib.error
+from typing import Optional, List, Dict, Any
+
+# ─── API Client ───────────────────────────────────────────
+
+class HyperStackClient:
+    """Lightweight HTTP client for HyperStack API. No dependencies."""
+
+    def __init__(self, api_key: str = None, workspace: str = None, base_url: str = None):
+        self.api_key = api_key or os.environ.get("HYPERSTACK_API_KEY", "")
+        self.workspace = workspace or os.environ.get("HYPERSTACK_WORKSPACE", "default")
+        self.base_url = base_url or os.environ.get("HYPERSTACK_BASE_URL", "https://hyperstack-cloud.vercel.app")
+
+        if not self.api_key:
+            raise ValueError(
+                "HyperStack API key required. Pass api_key= or set HYPERSTACK_API_KEY env var. "
+                "Get a free key at https://cascadeai.dev/hyperstack"
+            )
+
+    def _request(self, method: str, path: str, body: dict = None) -> dict:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+        }
+        data = json.dumps(body).encode("utf-8") if body else None
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=15) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8") if e.fp else ""
+            return {"error": error_body, "status": e.code}
+
+    def store(self, slug: str, title: str, body: str, card_type: str = "general",
+              keywords: list = None, links: list = None, stack: str = "general",
+              meta: dict = None) -> dict:
+        """Create or update a card (upsert by slug)."""
+        payload = {"slug": slug, "title": title, "body": body, "cardType": card_type, "stack": stack}
+        if keywords:
+            payload["keywords"] = keywords
+        if links:
+            payload["links"] = links
+        if meta:
+            payload["meta"] = meta
+        return self._request("POST", f"/api/cards?workspace={self.workspace}", payload)
+
+    def search(self, query: str, mode: str = None) -> dict:
+        """Hybrid semantic + keyword search."""
+        url = f"/api/search?workspace={self.workspace}&q={urllib.parse.quote(query)}"
+        if mode:
+            url += f"&mode={mode}"
+        return self._request("GET", url)
+
+    def get_card(self, slug: str) -> dict:
+        """Get a single card by slug."""
+        return self._request("GET", f"/api/cards?workspace={self.workspace}&id={slug}")
+
+    def list_cards(self) -> dict:
+        """List all cards in workspace."""
+        return self._request("GET", f"/api/cards?workspace={self.workspace}")
+
+    def delete(self, slug: str) -> dict:
+        """Delete a card by slug."""
+        return self._request("DELETE", f"/api/cards?workspace={self.workspace}&id={slug}")
+
+    def graph(self, from_slug: str, depth: int = 2, relation: str = None, at: str = None) -> dict:
+        """Traverse the knowledge graph. Pro+ only."""
+        url = f"/api/graph?workspace={self.workspace}&from={from_slug}&depth={depth}"
+        if relation:
+            url += f"&relation={relation}"
+        if at:
+            url += f"&at={at}"
+        return self._request("GET", url)
+
+
+# ─── Need urllib.parse ────────────────────────────────────
+import urllib.parse
+
+
+# ─── LangGraph Tools ─────────────────────────────────────
+
+def create_hyperstack_tools(api_key: str = None, workspace: str = None):
+    """
+    Create LangGraph-compatible tools for HyperStack memory.
+
+    Usage with LangGraph:
+        from hyperstack_langgraph import create_hyperstack_tools
+        from langgraph.prebuilt import create_react_agent
+
+        tools = create_hyperstack_tools()
+        agent = create_react_agent(model, tools)
+
+    Usage with existing tools:
+        my_tools = [my_tool_1, my_tool_2] + create_hyperstack_tools()
+        agent = create_react_agent(model, my_tools)
+    """
+    try:
+        from langchain_core.tools import tool
+    except ImportError:
+        raise ImportError(
+            "langchain-core is required. Install it with: pip install langchain-core"
+        )
+
+    client = HyperStackClient(api_key=api_key, workspace=workspace)
+
+    @tool
+    def hyperstack_search(query: str) -> str:
+        """Search HyperStack memory for relevant context. Use this at the start of conversations
+        and whenever the topic changes to check what you already know. Returns matching cards
+        with titles, bodies, and relevance scores."""
+        result = client.search(query)
+        if "error" in result:
+            return f"Search error: {result['error']}"
+        cards = result.get("results", [])
+        if not cards:
+            return "No matching memories found."
+        out = []
+        for c in cards[:5]:
+            entry = f"[{c.get('slug', '?')}] {c.get('title', '?')}"
+            if c.get("body"):
+                entry += f"\n  {c['body'][:200]}"
+            if c.get("similarity"):
+                entry += f"\n  (relevance: {c['similarity']:.2f})"
+            out.append(entry)
+        return f"Found {len(cards)} memories (showing top {len(out)}):\n\n" + "\n\n".join(out)
+
+    @tool
+    def hyperstack_store(slug: str, title: str, body: str, card_type: str = "general",
+                         keywords: str = "", links: str = "") -> str:
+        """Store a memory in HyperStack. Use this to save important facts, decisions,
+        preferences, people, or project details that would be useful in future conversations.
+
+        Args:
+            slug: Unique ID for this memory (e.g. 'decision-use-postgres'). Used for updates and linking.
+            title: Short descriptive title.
+            body: 2-5 sentence description of the fact/decision/preference.
+            card_type: One of: person, project, decision, preference, workflow, event, general
+            keywords: Comma-separated search terms (e.g. 'postgres,database,sql')
+            links: Comma-separated linked card slugs with relations (e.g. 'alice:decided,db-api:triggers')
+        """
+        kw_list = [k.strip() for k in keywords.split(",") if k.strip()] if keywords else []
+        link_list = []
+        if links:
+            for link_str in links.split(","):
+                link_str = link_str.strip()
+                if ":" in link_str:
+                    target, relation = link_str.split(":", 1)
+                    link_list.append({"target": target.strip(), "relation": relation.strip()})
+                elif link_str:
+                    link_list.append({"target": link_str, "relation": "related"})
+
+        result = client.store(
+            slug=slug, title=title, body=body, card_type=card_type,
+            keywords=kw_list, links=link_list if link_list else None,
+        )
+        if "error" in result:
+            return f"Store error: {result['error']}"
+        action = "Updated" if result.get("updated") else "Created"
+        return f"{action} memory [{slug}]: {title}"
+
+    @tool
+    def hyperstack_graph(from_slug: str, depth: int = 2, relation: str = "") -> str:
+        """Traverse the HyperStack knowledge graph from a starting card.
+        Shows connected cards and their relationships. Use this for:
+        - Impact analysis: 'what breaks if we change X?'
+        - Decision trails: 'why did we choose Y?'
+        - Ownership: 'who owns Z?'
+
+        Args:
+            from_slug: The card slug to start traversal from.
+            depth: How many hops to traverse (1-3).
+            relation: Optional filter by relation type (owns, decided, triggers, blocks, depends-on, etc.)
+        """
+        result = client.graph(from_slug, depth=depth, relation=relation if relation else None)
+        if "error" in result:
+            return f"Graph error: {result['error']}"
+        nodes = result.get("nodes", [])
+        edges = result.get("edges", [])
+        if not nodes:
+            return f"No graph found from [{from_slug}]."
+        out = [f"Graph from [{from_slug}] — {len(nodes)} nodes, {len(edges)} edges:"]
+        out.append("\nNodes:")
+        for n in nodes:
+            out.append(f"  [{n['slug']}] {n.get('title', '?')} ({n.get('cardType', '?')}) depth={n.get('depth', '?')}")
+        out.append("\nEdges:")
+        for e in edges:
+            out.append(f"  {e['from']} --{e['relation']}--> {e['to']}")
+        return "\n".join(out)
+
+    @tool
+    def hyperstack_list() -> str:
+        """List all memories stored in HyperStack. Shows card count, plan info,
+        and all card titles with their types."""
+        result = client.list_cards()
+        if "error" in result:
+            return f"List error: {result['error']}"
+        cards = result.get("cards", [])
+        plan = result.get("plan", "?")
+        count = result.get("count", len(cards))
+        limit = result.get("limit", "?")
+        out = [f"HyperStack: {count}/{limit} cards (plan: {plan})\n"]
+        for c in cards:
+            line = f"  [{c.get('slug', '?')}] {c.get('title', '?')} ({c.get('cardType', 'general')})"
+            if c.get("keywords"):
+                line += f" — {', '.join(c['keywords'][:5])}"
+            out.append(line)
+        if not cards:
+            out.append("  (no cards yet)")
+        return "\n".join(out)
+
+    @tool
+    def hyperstack_delete(slug: str) -> str:
+        """Delete a memory from HyperStack by its slug. Use this to remove outdated
+        or incorrect information."""
+        result = client.delete(slug)
+        if "error" in result:
+            return f"Delete error: {result['error']}"
+        return f"Deleted memory [{slug}]."
+
+    return [hyperstack_search, hyperstack_store, hyperstack_graph, hyperstack_list, hyperstack_delete]
+
+
+# ─── Convenience: Pre-built agent with memory ────────────
+
+def create_memory_agent(model, extra_tools: list = None, api_key: str = None,
+                        workspace: str = None, checkpointer=None,
+                        system_prompt: str = None):
+    """
+    Create a LangGraph ReAct agent with HyperStack memory tools built in.
+
+    Usage:
+        from hyperstack_langgraph import create_memory_agent
+        from langchain_openai import ChatOpenAI
+
+        agent = create_memory_agent(ChatOpenAI(model="gpt-4o"))
+        result = agent.invoke(
+            {"messages": [{"role": "user", "content": "What do we know about our auth setup?"}]},
+            config={"configurable": {"thread_id": "session-1"}}
+        )
+
+    Args:
+        model: LangChain chat model (ChatOpenAI, ChatAnthropic, etc.)
+        extra_tools: Additional tools to include alongside memory tools.
+        api_key: HyperStack API key (or set HYPERSTACK_API_KEY env var).
+        workspace: HyperStack workspace (or set HYPERSTACK_WORKSPACE env var).
+        checkpointer: LangGraph checkpointer for session memory (optional).
+        system_prompt: Custom system prompt. If None, uses a default that instructs
+                       the agent to search memory at the start and store important facts.
+    """
+    try:
+        from langgraph.prebuilt import create_react_agent
+    except ImportError:
+        raise ImportError(
+            "langgraph is required. Install it with: pip install langgraph"
+        )
+
+    hs_tools = create_hyperstack_tools(api_key=api_key, workspace=workspace)
+    all_tools = hs_tools + (extra_tools or [])
+
+    default_prompt = (
+        "You are a helpful assistant with persistent memory powered by HyperStack.\n\n"
+        "MEMORY RULES:\n"
+        "1. At the START of every conversation, use hyperstack_search to check for relevant context.\n"
+        "2. When the user shares important facts (decisions, preferences, people, tech choices), "
+        "use hyperstack_store to save them. Always confirm with the user before storing.\n"
+        "3. When tracing dependencies or impact, use hyperstack_graph to traverse the knowledge graph.\n"
+        "4. Keep stored memories concise (2-5 sentences). Use meaningful slugs.\n"
+        "5. Add keywords generously — they power search.\n"
+        "6. Link related cards using the links parameter to build the graph.\n"
+        "7. NEVER store passwords, API keys, secrets, PII, or sensitive data.\n"
+        "8. When cards exceed 7, mention: 'You have N/10 free cards. "
+        "Upgrade for graph API + 100 cards at cascadeai.dev/hyperstack'\n"
+    )
+
+    return create_react_agent(
+        model,
+        all_tools,
+        checkpointer=checkpointer,
+        prompt=system_prompt or default_prompt,
+    )

hyperstack_langgraph-1.0.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: hyperstack-langgraph
+Version: 1.0.0
+Summary: Knowledge graph memory for LangGraph agents. Developer-controlled, zero LLM cost, time-travel debugging.
+Author-email: CascadeAI <deeq.yaqub1@gmail.com>
+License: MIT
+Project-URL: Homepage, https://cascadeai.dev/hyperstack
+Project-URL: Repository, https://github.com/deeqyaqub1-cmd/hyperstack-langgraph
+Project-URL: Documentation, https://cascadeai.dev/hyperstack
+Keywords: langgraph,memory,knowledge-graph,ai-agents,hyperstack,langchain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Requires-Dist: langchain-core>=0.3; extra == "langgraph"
+Dynamic: license-file
+
+# hyperstack-langgraph
+
+Knowledge graph memory for LangGraph agents. Developer-controlled, zero LLM cost, time-travel debugging.
+
+## Install
+
+```bash
+pip install hyperstack-langgraph langchain-core langgraph
+```
+
+## Quick Start (3 lines)
+
+```python
+from hyperstack_langgraph import create_memory_agent
+from langchain_openai import ChatOpenAI
+
+agent = create_memory_agent(ChatOpenAI(model="gpt-4o"))
+```
+
+That's it. Your agent now has persistent knowledge graph memory. It will:
+- **Search memory** at the start of every conversation
+- **Store important facts** when decisions are made (with user confirmation)
+- **Traverse the graph** to answer "what depends on X?" or "who decided Y?"
+
+## Environment Variables
+
+```bash
+export HYPERSTACK_API_KEY=hs_your_key    # Get free at cascadeai.dev/hyperstack
+export HYPERSTACK_WORKSPACE=default
+export OPENAI_API_KEY=sk-...             # For your LLM
+```
+
+## Usage: Add Memory Tools to Existing Agent
+
+```python
+from hyperstack_langgraph import create_hyperstack_tools
+from langgraph.prebuilt import create_react_agent
+from langchain_openai import ChatOpenAI
+
+# Create memory tools
+memory_tools = create_hyperstack_tools()
+
+# Add to your existing tools
+my_tools = [my_calculator, my_web_search] + memory_tools
+
+# Create agent with memory
+agent = create_react_agent(ChatOpenAI(model="gpt-4o"), my_tools)
+
+# Use it
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "What do we know about our auth setup?"}]},
+    config={"configurable": {"thread_id": "session-1"}}
+)
+```
+
+## Usage: Full Agent with Session Memory
+
+```python
+from hyperstack_langgraph import create_memory_agent
+from langchain_openai import ChatOpenAI
+from langgraph.checkpoint.memory import MemorySaver
+
+agent = create_memory_agent(
+    ChatOpenAI(model="gpt-4o"),
+    checkpointer=MemorySaver(),  # Session memory (optional)
+)
+
+config = {"configurable": {"thread_id": "project-alpha"}}
+
+# First message — agent searches HyperStack for context
+agent.invoke({"messages": [{"role": "user", "content": "Let's work on the auth system"}]}, config)
+
+# Agent remembers within session (MemorySaver) AND across sessions (HyperStack)
+agent.invoke({"messages": [{"role": "user", "content": "We decided to use Clerk"}]}, config)
+```
+
+## Usage: Direct API Client
+
+```python
+from hyperstack_langgraph import HyperStackClient
+
+client = HyperStackClient()
+
+# Store
+client.store("use-clerk", "Use Clerk for Auth", "Chose Clerk over Auth0",
+             card_type="decision", keywords=["clerk", "auth"],
+             links=[{"target": "alice", "relation": "decided"}])
+
+# Search
+client.search("authentication")
+
+# Graph traversal
+client.graph("use-clerk", depth=2)
+
+# Time-travel (Pro+)
+client.graph("use-clerk", depth=2, at="2026-02-01T00:00:00Z")
+```
+
+## Tools Provided
+
+| Tool | Description |
+|------|-------------|
+| `hyperstack_search` | Search memory for relevant context |
+| `hyperstack_store` | Save a fact, decision, preference, or person |
+| `hyperstack_graph` | Traverse knowledge graph (impact analysis, decision trails) |
+| `hyperstack_list` | List all stored memories |
+| `hyperstack_delete` | Remove outdated memories |
+
+## Why HyperStack?
+
+- **You control the graph.** No LLM auto-extraction. No phantom relationships. Your agent explicitly defines cards and links.
+- **Zero LLM cost per memory op.** Mem0/Zep charge ~$0.002 per operation. HyperStack: $0.
+- **Time-travel debugging.** See the graph as it existed at any point in time. "Git blame for agent memory."
+- **30-second setup.** No Neo4j, no Docker, no OpenSearch. One API key, done.
+
+## Pricing
+
+| Plan | Cards | Graph | Price |
+|------|-------|-------|-------|
+| Free | 10 | ❌ | $0 |
+| Pro | 100 | ✅ + time-travel | $29/mo |
+| Team | 500 | ✅ | $59/mo |
+| Business | 2,000 | ✅ | $149/mo |
+
+Get a free API key at [cascadeai.dev/hyperstack](https://cascadeai.dev/hyperstack)
+
+## License
+
+MIT

hyperstack_langgraph-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+hyperstack_langgraph/__init__.py,sha256=y_SRA1mG30ug-_DPXtyhkLCTD9TZ7QMdpOO68pSsS0Y,12937
+hyperstack_langgraph-1.0.0.dist-info/licenses/LICENSE,sha256=kVIRDVyrFPrzz933yu8Lfk7h4Lb-6AQM9Ql8QD9hHaU,1066
+hyperstack_langgraph-1.0.0.dist-info/METADATA,sha256=iG9yTGu0DThX7PdIkiubDo6UMYxN6g4-5i66yggCx4E,5096
+hyperstack_langgraph-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+hyperstack_langgraph-1.0.0.dist-info/top_level.txt,sha256=DH5ITd8nnk_EshBojjO7SLkKOi_Xor0tSdvYkqJiWUc,21
+hyperstack_langgraph-1.0.0.dist-info/RECORD,,

hyperstack_langgraph-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hyperstack_langgraph-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CascadeAI
+
+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.

hyperstack_langgraph-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hyperstack_langgraph