hyperstack-py 1.0.0__py3-none-any.whl

hyperstack/__init__.py

@@ -0,0 +1,221 @@
+"""
+HyperStack Python SDK
+Cloud memory for AI agents. 3 lines to integrate.
+
+Usage:
+    from hyperstack import HyperStack
+
+    hs = HyperStack("hs_your_key")
+    hs.store("project-api", "API", "FastAPI on AWS", stack="projects", keywords=["fastapi", "python"])
+    results = hs.search("python")
+    cards = hs.list()
+    hs.delete("project-api")
+    stats = hs.stats()
+
+Install:
+    pip install hyperstack-py
+
+Docs: https://cascadeai.dev
+"""
+
+import json
+import urllib.request
+import urllib.error
+import urllib.parse
+from typing import Optional, List, Dict, Any
+
+__version__ = "1.0.0"
+
+DEFAULT_API_URL = "https://hyperstack-cloud.vercel.app"
+
+
+class HyperStackError(Exception):
+    """Base exception for HyperStack errors."""
+    def __init__(self, message: str, status: int = 0):
+        super().__init__(message)
+        self.status = status
+
+
+class HyperStack:
+    """
+    HyperStack client — cloud memory for AI agents.
+
+    Args:
+        api_key: Your HyperStack API key (starts with hs_)
+        workspace: Workspace name (default: "default")
+        api_url: API base URL (default: production)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace: str = "default",
+        api_url: str = DEFAULT_API_URL,
+    ):
+        if not api_key:
+            raise HyperStackError("API key required. Get one free at https://cascadeai.dev")
+        self.api_key = api_key
+        self.workspace = workspace
+        self.api_url = api_url.rstrip("/")
+
+    def _request(self, endpoint: str, method: str = "GET", body: Optional[dict] = None, params: Optional[dict] = None) -> dict:
+        """Make an API request."""
+        url = f"{self.api_url}/api/{endpoint}?workspace={urllib.parse.quote(self.workspace)}"
+        if params:
+            for k, v in params.items():
+                url += f"&{urllib.parse.quote(k)}={urllib.parse.quote(str(v))}"
+
+        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) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body_text = e.read().decode("utf-8", errors="replace")
+            try:
+                err_data = json.loads(body_text)
+                msg = err_data.get("error", body_text)
+            except Exception:
+                msg = body_text
+            raise HyperStackError(msg, status=e.code)
+        except urllib.error.URLError as e:
+            raise HyperStackError(f"Connection failed: {e.reason}")
+
+    def store(
+        self,
+        slug: str,
+        title: str,
+        body: str,
+        stack: str = "general",
+        keywords: Optional[List[str]] = None,
+    ) -> dict:
+        """
+        Store or update a memory card.
+
+        Args:
+            slug: Unique ID (kebab-case, e.g. "project-webapp")
+            title: Short title
+            body: The knowledge to remember
+            stack: Category (projects|people|decisions|preferences|workflows|general)
+            keywords: Tags for search
+
+        Returns:
+            Card data dict
+        """
+        return self._request("cards", method="POST", body={
+            "slug": slug,
+            "title": title,
+            "body": body,
+            "stack": stack,
+            "keywords": keywords or [],
+        })
+
+    def search(self, query: str) -> List[dict]:
+        """
+        Search memory cards.
+
+        Args:
+            query: Search term
+
+        Returns:
+            List of matching cards
+        """
+        result = self._request("search", params={"q": query})
+        return result.get("cards", [])
+
+    def list(self, stack: Optional[str] = None) -> List[dict]:
+        """
+        List all memory cards.
+
+        Args:
+            stack: Filter by stack (optional)
+
+        Returns:
+            List of all cards
+        """
+        result = self._request("cards")
+        cards = result.get("cards", [])
+        if stack:
+            cards = [c for c in cards if c.get("stack") == stack]
+        return cards
+
+    def get(self, slug: str) -> Optional[dict]:
+        """
+        Get a specific card by slug.
+
+        Args:
+            slug: Card slug
+
+        Returns:
+            Card dict or None
+        """
+        cards = self.list()
+        for card in cards:
+            if card.get("slug") == slug:
+                return card
+        return None
+
+    def delete(self, slug: str) -> dict:
+        """
+        Delete a memory card.
+
+        Args:
+            slug: Card slug to delete
+
+        Returns:
+            Response dict
+        """
+        return self._request("cards", method="DELETE", params={"id": slug})
+
+    def stats(self) -> dict:
+        """
+        Get memory usage stats.
+
+        Returns:
+            Dict with card count, plan, limit, token stats
+        """
+        result = self._request("cards")
+        cards = result.get("cards", [])
+        total_tokens = sum(c.get("tokens", 0) for c in cards)
+        without_hs = len(cards) * 6000
+
+        stacks: Dict[str, int] = {}
+        for c in cards:
+            s = c.get("stack", "general")
+            stacks[s] = stacks.get(s, 0) + 1
+
+        return {
+            "cards": len(cards),
+            "plan": result.get("plan", "FREE"),
+            "limit": result.get("limit", 50),
+            "tokens_stored": total_tokens,
+            "tokens_without_hs": without_hs,
+            "savings_pct": round((1 - total_tokens / without_hs) * 100) if without_hs > 0 else 0,
+            "stacks": stacks,
+        }
+
+    def ingest(self, text: str, source: str = "conversation") -> dict:
+        """
+        Auto-extract memory cards from raw text.
+
+        Args:
+            text: Raw conversation or document text
+            source: Source identifier
+
+        Returns:
+            Dict with extracted count and created cards
+        """
+        return self._request("ingest", method="POST", body={
+            "text": text,
+            "workspace": self.workspace,
+            "source": source,
+        })
+
+    def __repr__(self) -> str:
+        return f"HyperStack(workspace='{self.workspace}', key='...{self.api_key[-6:]}')"

hyperstack_py-1.0.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hyperstack-py
+Version: 1.0.0
+Summary: Cloud memory for AI agents. 3 lines to integrate. No SDK dependencies.
+Home-page: https://cascadeai.dev
+Author: CascadeAI
+Author-email: deeq.yaqub1@gmail.com
+License: MIT
+Project-URL: Documentation, https://cascadeai.dev
+Project-URL: Source, https://github.com/deeqyaqub1-cmd/hyperstack-py
+Project-URL: Discord, https://discord.gg/tdnXaV6e
+Keywords: ai memory agent llm hyperstack mcp claude cursor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# 🃏 HyperStack Python SDK
+
+**Cloud memory for AI agents. Zero dependencies. 3 lines to integrate.**
+
+## Install
+
+```bash
+pip install hyperstack-py
+```
+
+## Quick Start
+
+```python
+from hyperstack import HyperStack
+
+hs = HyperStack("hs_your_key")
+
+# Store a memory
+hs.store("project-api", "API", "FastAPI 3.12 on AWS", stack="projects", keywords=["fastapi", "python"])
+
+# Search memories
+results = hs.search("python")
+
+# List all cards
+cards = hs.list()
+
+# Delete a card
+hs.delete("project-api")
+
+# Get usage stats
+stats = hs.stats()
+print(f"Saving {stats['savings_pct']}% on tokens!")
+
+# Auto-extract from conversation text
+hs.ingest("Alice is a senior engineer. We decided to use FastAPI over Django.")
+```
+
+## Why HyperStack?
+
+- **Zero dependencies** — just Python stdlib
+- **No LLM costs** — memory ops are free
+- **94% token savings** — ~350 tokens vs ~6,000 per message
+- **30-second setup** — get key at [cascadeai.dev](https://cascadeai.dev)
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `store(slug, title, body, stack, keywords)` | Create/update a card |
+| `search(query)` | Search cards |
+| `list(stack=None)` | List all cards |
+| `get(slug)` | Get one card |
+| `delete(slug)` | Delete a card |
+| `stats()` | Usage summary |
+| `ingest(text)` | Auto-extract memories |
+
+## Get a free key
+
+→ [cascadeai.dev](https://cascadeai.dev) — 50 cards free, no credit card.
+
+## License
+
+MIT © [CascadeAI](https://cascadeai.dev)

hyperstack_py-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+hyperstack/__init__.py,sha256=HtBk0gfwJEHU3RK2d65kOiYUV5W1pqVXWbATdec4MC8,6324
+hyperstack_py-1.0.0.dist-info/METADATA,sha256=Ty1WnwtxWG_FxNyf7R2CPI7wgGAZ_DoIhkFsQH_MOIo,2631
+hyperstack_py-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+hyperstack_py-1.0.0.dist-info/top_level.txt,sha256=njn3-XmjCMziM6_3QadnDQbqsVh2KYw4J1IysqyY0HI,11
+hyperstack_py-1.0.0.dist-info/RECORD,,

hyperstack_py-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_py-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hyperstack