Metadata-Version: 2.4
Name: hyperstack-py
Version: 1.5.4
Summary: The Agent Provenance Graph for AI agents. Timestamped facts, auditable decisions, deterministic trust. Prove what agents knew, trace why they knew it, coordinate without an LLM in the loop. $0 per operation.
Home-page: https://cascadeai.dev
Author: CascadeAI
Author-email: deeq@cascadeai.dev
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

**The Agent Provenance Graph for AI agents** — the only memory layer where agents can prove what they knew, trace why they knew it, and coordinate without an LLM in the loop. $0 per operation at any scale.

*Timestamped facts. Auditable decisions. Deterministic trust. Build agents you can trust at $0/operation.*

## Install

```bash
pip install hyperstack-py
```

Current version: **v1.5.3**

## 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")

# Get a single card
card = hs.get("project-api")

# List all cards
cards = hs.list()

# Delete a card
hs.delete("project-api")

# Graph traversal (what blocks X? what does X affect?)
blockers = hs.blockers("deploy-prod")
impact = hs.impact("use-clerk")

# Time-travel: graph at a past timestamp
graph = hs.graph("auth-api", at="2026-02-01T00:00:00Z")

# Utility-weighted edges (report success/failure)
hs.feedback(card_slugs=["use-clerk"], outcome="success")

# Git-style branching
branch = hs.fork(branch_name="experiment")
hs.diff(branch_workspace_id=branch["branchWorkspaceId"])
hs.merge(branch_workspace_id=branch["branchWorkspaceId"], strategy="branch-wins")

# Agent identity + trust
hs.identify(agent_slug="research-agent")
profile = hs.profile(agent_slug="research-agent")

# Ingest conversation transcript into cards
hs.auto_remember("Alice is a senior engineer. We decided to use FastAPI over Django.")

# Memory hub: working (TTL) / semantic (permanent) / episodic (30-day decay)
cards = hs.hs_memory(surface="semantic")

# Batch store multiple cards
hs.bulk_store([{"slug": "p1", "title": "Project A", "body": "..."}, {"slug": "p2", "title": "Project B", "body": "..."}])

# Parse markdown/logs into cards (CLI + programmatic)
hs.parse("# DECISIONS.md content or log output", source="decisions")

# Agentic routing: deterministic, no LLM
can_do = hs.can("auth-api", action="deploy")    # Can this card do X?
steps = hs.plan("auth-api", goal="add 2FA")     # Plan steps for goal
```

## API Reference

| Method | Description |
|--------|-------------|
| `store(slug, title, body, ...)` | Create/update a card |
| `bulk_store(cards)` | Batch store multiple cards |
| `get(slug)` | Get one card |
| `search(query)` | Search cards |
| `list(stack=None)` | List all cards |
| `delete(slug)` | Delete a card |
| `graph(from_slug, depth, at, reverse)` | Forward/reverse traversal + time-travel |
| `blockers(slug)` | What blocks a card |
| `impact(slug)` | Blast radius of a change |
| `feedback(card_slugs, outcome)` | Report success/failure, updates utility scores on edges |
| `fork(branch_name)` | Git-style branch |
| `diff(branch_workspace_id)` | Compare branch to parent |
| `merge(branch_workspace_id, strategy)` | Merge branch |
| `discard(branch_workspace_id)` | Delete branch |
| `identify(agent_slug)` | Register agent identity |
| `profile(agent_slug)` | Get agent trust score |
| `can(slug, action)` | Agentic routing: can this card do X? (deterministic, no LLM) |
| `plan(slug, goal)` | Agentic routing: plan steps for goal |
| `auto_remember(text)` | Ingest conversation transcript into cards |
| `hs_memory(surface)` | Memory hub: working / semantic / episodic |
| `parse(text, source)` | Parse markdown/logs into cards |

## Card Fields

| Field | Description |
|-------|-------------|
| `confidence` | 0.0–1.0 confidence score |
| `truthStratum` | `draft` \| `hypothesis` \| `confirmed` |
| `verifiedBy` | e.g. `"human:deeq"` |
| `verifiedAt` | Auto-set server-side |
| `memoryType` | `working` \| `semantic` \| `episodic` |
| `ttl` | Working memory expiry (seconds) |
| `sourceAgent` | Auto-stamped after `identify()` |

## Backend Features

- **Conflict detection** — structural, no LLM, auto-detects contradicting cards
- **Staleness cascade** — upstream changes mark dependents stale
- **Three memory surfaces** — working (TTL), semantic (permanent), episodic (30-day decay)
- **Decision replay** — reconstruct agent state at decision time + hindsight detection
- **Time-travel** — `graph()` with `at=` timestamp
- **Self-hosting** — Docker + `HYPERSTACK_BASE_URL` env var

## Why HyperStack?

- **Provenance tracking** — timestamped facts, auditable decisions
- **Decision replay** — reconstruct what agents knew at decision time
- **Deterministic trust** — no LLM in the loop for coordination
- **$0 per operation** — at any scale
- **Zero dependencies** — just Python stdlib
- **30-second setup** — get key at [cascadeai.dev/hyperstack](https://cascadeai.dev/hyperstack)

## Pricing

| Plan | Cards | Price |
|------|-------|-------|
| Free | 50 | $0/mo — ALL features including graph |
| Pro | 500+ | $29/mo |
| Team | 500, 5 API keys | $59/mo |
| Business | 2,000, 20 members | $149/mo |

Get a free key: [cascadeai.dev/hyperstack](https://cascadeai.dev/hyperstack)

## License

MIT © [CascadeAI](https://cascadeai.dev)
