hippocortex 1.0.0__tar.gz

hippocortex-1.0.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: hippocortex
+Version: 1.0.0
+Summary: Official Hippocortex Python SDK — AI agent memory that learns from experience
+Author-email: Hippocortex <dev@hippocortex.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://hippocortex.dev
+Project-URL: Documentation, https://docs.hippocortex.dev
+Project-URL: Repository, https://github.com/hippocortex/hippocortex-os
+Project-URL: Bug Tracker, https://github.com/hippocortex/hippocortex-os/issues
+Project-URL: Changelog, https://github.com/hippocortex/hippocortex-os/blob/main/CHANGELOG.md
+Keywords: hippocortex,ai,memory,agents,llm,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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1.0; extra == "openai-agents"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.50.0; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
+Provides-Extra: all
+Requires-Dist: openai-agents>=0.1.0; extra == "all"
+Requires-Dist: langgraph>=0.2.0; extra == "all"
+Requires-Dist: crewai>=0.50.0; extra == "all"
+Requires-Dist: pyautogen>=0.2.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# hippocortex
+
+Official Python SDK for [Hippocortex](https://hippocortex.dev) — AI agent memory that learns from experience.
+
+## Install
+
+```bash
+pip install hippocortex
+
+# With adapter support:
+pip install hippocortex[openai-agents]  # OpenAI Agents SDK
+pip install hippocortex[langgraph]      # LangGraph
+pip install hippocortex[crewai]         # CrewAI
+pip install hippocortex[autogen]        # AutoGen
+pip install hippocortex[all]            # All adapters
+```
+
+## Quick Start
+
+### Direct Client Usage
+
+```python
+import asyncio
+from hippocortex import Hippocortex
+from hippocortex.types import CaptureEvent
+
+async def main():
+    hx = Hippocortex(api_key="hx_live_...")
+
+    # 1. Capture agent events
+    await hx.capture(CaptureEvent(
+        type="message",
+        session_id="sess-1",
+        payload={"role": "user", "content": "Deploy payment service to staging"}
+    ))
+
+    # 2. Learn from experience
+    await hx.learn()
+
+    # 3. Synthesize context for decisions
+    ctx = await hx.synthesize("deploy payment service")
+    for entry in ctx.entries:
+        print(f"[{entry.section}] {entry.content}")
+
+asyncio.run(main())
+```
+
+### Synchronous Client
+
+```python
+from hippocortex import SyncHippocortex
+from hippocortex.types import CaptureEvent
+
+hx = SyncHippocortex(api_key="hx_live_...")
+
+result = hx.capture(CaptureEvent(
+    type="message",
+    session_id="sess-1",
+    payload={"role": "user", "content": "Hello"}
+))
+print(result.event_id)
+```
+
+## Auto-Memory Adapters
+
+Wrap your agents with **one line** to get automatic memory capture and context injection.
+
+### OpenAI Agents SDK
+
+```python
+from agents import Agent, Runner
+from hippocortex import auto_memory
+
+agent = Agent(name="assistant", instructions="You are helpful.")
+agent = auto_memory(agent, api_key="hx_live_...")
+
+# Or with env var HIPPOCORTEX_API_KEY:
+agent = auto_memory(agent)
+
+result = await Runner.run(agent, "Deploy to staging")
+```
+
+The adapter automatically:
+- Synthesizes past context before each run (injected into instructions)
+- Captures user messages, assistant responses, and tool calls
+- Gracefully degrades if the server is unreachable
+
+### LangGraph
+
+```python
+from hippocortex.adapters import langgraph as hx_langgraph
+
+# Wrap a compiled LangGraph
+graph = builder.compile()
+graph = hx_langgraph.wrap(graph, api_key="hx_live_...")
+
+# Use normally — memory is automatic
+result = await graph.ainvoke({"messages": [{"role": "user", "content": "deploy"}]})
+```
+
+Supports `ainvoke`, `invoke`, and `astream`.
+
+### CrewAI (Beta)
+
+```python
+from hippocortex.adapters import crewai as hx_crewai
+
+crew = hx_crewai.wrap(crew, api_key="hx_live_...")
+result = crew.kickoff()
+```
+
+Injects memory context into agent backstories and captures task results.
+
+### AutoGen (Beta)
+
+```python
+from hippocortex.adapters import autogen as hx_autogen
+
+agent = hx_autogen.wrap(agent, api_key="hx_live_...")
+agent.initiate_chat(other_agent, message="Hello")
+```
+
+Captures messages and injects synthesized context via reply hooks.
+
+### OpenClaw
+
+```python
+from hippocortex.adapters import openclaw as hx_openclaw
+
+middleware = hx_openclaw.create_middleware(api_key="hx_live_...")
+
+# On incoming message:
+context = await middleware.on_message("Deploy the service")
+# context = "# Hippocortex Memory Context\n..."
+
+# After generating response:
+await middleware.on_response("Deployment complete!")
+```
+
+## Configuration
+
+All adapters support:
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `api_key` | `HIPPOCORTEX_API_KEY` | (required) | API key |
+| `base_url` | `HIPPOCORTEX_BASE_URL` | `https://api.hippocortex.dev/v1` | API URL |
+| `session_id` | — | auto-generated | Session ID |
+
+## Key Behaviors
+
+- **Fire-and-forget capture**: Capture calls never block the agent
+- **Error swallowing**: All Hippocortex errors are logged and swallowed — your agent never crashes because of memory
+- **Graceful degradation**: If the server is unreachable, adapters return empty context and continue
+- **Session tracking**: Auto-generated session IDs link related events
+
+## API Reference
+
+### `Hippocortex(api_key, base_url?, timeout?)`
+
+Async client. Use with `await`.
+
+- `capture(event)` → `CaptureResult`
+- `capture_batch(events)` → `BatchCaptureResult`
+- `learn(options?)` → `LearnResult`
+- `synthesize(query, options?)` → `SynthesizeResult`
+- `list_artifacts(...)` → `ArtifactListResult`
+- `get_artifact(id)` → `Artifact`
+- `get_metrics(...)` → `MetricsResult`
+
+### `SyncHippocortex(api_key, base_url?, timeout?)`
+
+Synchronous client. Same methods, no `await` needed.
+
+## License
+
+MIT

hippocortex-1.0.0/README.md

@@ -0,0 +1,177 @@
+# hippocortex
+
+Official Python SDK for [Hippocortex](https://hippocortex.dev) — AI agent memory that learns from experience.
+
+## Install
+
+```bash
+pip install hippocortex
+
+# With adapter support:
+pip install hippocortex[openai-agents]  # OpenAI Agents SDK
+pip install hippocortex[langgraph]      # LangGraph
+pip install hippocortex[crewai]         # CrewAI
+pip install hippocortex[autogen]        # AutoGen
+pip install hippocortex[all]            # All adapters
+```
+
+## Quick Start
+
+### Direct Client Usage
+
+```python
+import asyncio
+from hippocortex import Hippocortex
+from hippocortex.types import CaptureEvent
+
+async def main():
+    hx = Hippocortex(api_key="hx_live_...")
+
+    # 1. Capture agent events
+    await hx.capture(CaptureEvent(
+        type="message",
+        session_id="sess-1",
+        payload={"role": "user", "content": "Deploy payment service to staging"}
+    ))
+
+    # 2. Learn from experience
+    await hx.learn()
+
+    # 3. Synthesize context for decisions
+    ctx = await hx.synthesize("deploy payment service")
+    for entry in ctx.entries:
+        print(f"[{entry.section}] {entry.content}")
+
+asyncio.run(main())
+```
+
+### Synchronous Client
+
+```python
+from hippocortex import SyncHippocortex
+from hippocortex.types import CaptureEvent
+
+hx = SyncHippocortex(api_key="hx_live_...")
+
+result = hx.capture(CaptureEvent(
+    type="message",
+    session_id="sess-1",
+    payload={"role": "user", "content": "Hello"}
+))
+print(result.event_id)
+```
+
+## Auto-Memory Adapters
+
+Wrap your agents with **one line** to get automatic memory capture and context injection.
+
+### OpenAI Agents SDK
+
+```python
+from agents import Agent, Runner
+from hippocortex import auto_memory
+
+agent = Agent(name="assistant", instructions="You are helpful.")
+agent = auto_memory(agent, api_key="hx_live_...")
+
+# Or with env var HIPPOCORTEX_API_KEY:
+agent = auto_memory(agent)
+
+result = await Runner.run(agent, "Deploy to staging")
+```
+
+The adapter automatically:
+- Synthesizes past context before each run (injected into instructions)
+- Captures user messages, assistant responses, and tool calls
+- Gracefully degrades if the server is unreachable
+
+### LangGraph
+
+```python
+from hippocortex.adapters import langgraph as hx_langgraph
+
+# Wrap a compiled LangGraph
+graph = builder.compile()
+graph = hx_langgraph.wrap(graph, api_key="hx_live_...")
+
+# Use normally — memory is automatic
+result = await graph.ainvoke({"messages": [{"role": "user", "content": "deploy"}]})
+```
+
+Supports `ainvoke`, `invoke`, and `astream`.
+
+### CrewAI (Beta)
+
+```python
+from hippocortex.adapters import crewai as hx_crewai
+
+crew = hx_crewai.wrap(crew, api_key="hx_live_...")
+result = crew.kickoff()
+```
+
+Injects memory context into agent backstories and captures task results.
+
+### AutoGen (Beta)
+
+```python
+from hippocortex.adapters import autogen as hx_autogen
+
+agent = hx_autogen.wrap(agent, api_key="hx_live_...")
+agent.initiate_chat(other_agent, message="Hello")
+```
+
+Captures messages and injects synthesized context via reply hooks.
+
+### OpenClaw
+
+```python
+from hippocortex.adapters import openclaw as hx_openclaw
+
+middleware = hx_openclaw.create_middleware(api_key="hx_live_...")
+
+# On incoming message:
+context = await middleware.on_message("Deploy the service")
+# context = "# Hippocortex Memory Context\n..."
+
+# After generating response:
+await middleware.on_response("Deployment complete!")
+```
+
+## Configuration
+
+All adapters support:
+
+| Option | Env Var | Default | Description |
+|--------|---------|---------|-------------|
+| `api_key` | `HIPPOCORTEX_API_KEY` | (required) | API key |
+| `base_url` | `HIPPOCORTEX_BASE_URL` | `https://api.hippocortex.dev/v1` | API URL |
+| `session_id` | — | auto-generated | Session ID |
+
+## Key Behaviors
+
+- **Fire-and-forget capture**: Capture calls never block the agent
+- **Error swallowing**: All Hippocortex errors are logged and swallowed — your agent never crashes because of memory
+- **Graceful degradation**: If the server is unreachable, adapters return empty context and continue
+- **Session tracking**: Auto-generated session IDs link related events
+
+## API Reference
+
+### `Hippocortex(api_key, base_url?, timeout?)`
+
+Async client. Use with `await`.
+
+- `capture(event)` → `CaptureResult`
+- `capture_batch(events)` → `BatchCaptureResult`
+- `learn(options?)` → `LearnResult`
+- `synthesize(query, options?)` → `SynthesizeResult`
+- `list_artifacts(...)` → `ArtifactListResult`
+- `get_artifact(id)` → `Artifact`
+- `get_metrics(...)` → `MetricsResult`
+
+### `SyncHippocortex(api_key, base_url?, timeout?)`
+
+Synchronous client. Same methods, no `await` needed.
+
+## License
+
+MIT

hippocortex-1.0.0/hippocortex/__init__.py

@@ -0,0 +1,79 @@
+"""Hippocortex — AI agent memory that learns from experience.
+
+Usage::
+
+    from hippocortex import Hippocortex, auto_memory
+
+    # Direct client usage
+    hx = Hippocortex(api_key="hx_live_...")
+
+    # One-line auto-memory for OpenAI Agents
+    agent = auto_memory(agent, api_key="hx_live_...")
+"""
+
+from .client import Hippocortex, HippocortexError, SyncHippocortex
+from .types import (
+    Artifact,
+    ArtifactListResult,
+    ArtifactStatus,
+    ArtifactType,
+    BatchCaptureResult,
+    CaptureEvent,
+    CaptureEventType,
+    CaptureResult,
+    LearnOptions,
+    LearnResult,
+    MetricsResult,
+    ProvenanceRef,
+    ReasoningSection,
+    SynthesisEntry,
+    SynthesizeBudget,
+    SynthesizeOptions,
+    SynthesizeResult,
+)
+
+
+def auto_memory(agent, api_key=None, base_url=None, session_id=None, **kwargs):
+    """One-line auto-memory wrapper for OpenAI Agents SDK.
+
+    Wraps an agent to automatically capture events and inject synthesized
+    context from Hippocortex memory.
+
+    Args:
+        agent: An OpenAI Agents SDK ``Agent`` instance.
+        api_key: Hippocortex API key. Falls back to ``HIPPOCORTEX_API_KEY`` env var.
+        base_url: API base URL override.
+        session_id: Explicit session ID (auto-generated if omitted).
+        **kwargs: Passed to the OpenAI adapter.
+
+    Returns:
+        The wrapped agent (same type, with memory hooks attached).
+    """
+    from .adapters.openai_agents import wrap
+
+    return wrap(agent, api_key=api_key, base_url=base_url, session_id=session_id, **kwargs)
+
+
+__all__ = [
+    "Hippocortex",
+    "HippocortexError",
+    "SyncHippocortex",
+    "auto_memory",
+    "Artifact",
+    "ArtifactListResult",
+    "ArtifactStatus",
+    "ArtifactType",
+    "BatchCaptureResult",
+    "CaptureEvent",
+    "CaptureEventType",
+    "CaptureResult",
+    "LearnOptions",
+    "LearnResult",
+    "MetricsResult",
+    "ProvenanceRef",
+    "ReasoningSection",
+    "SynthesisEntry",
+    "SynthesizeBudget",
+    "SynthesizeOptions",
+    "SynthesizeResult",
+]

hippocortex-1.0.0/hippocortex/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Hippocortex adapters — auto-memory for popular agent frameworks.
+
+Available adapters:
+    - ``openai_agents`` — OpenAI Agents SDK
+    - ``langgraph`` — LangGraph
+    - ``crewai`` — CrewAI
+    - ``autogen`` — AutoGen
+    - ``openclaw`` — OpenClaw
+"""
+
+__all__ = [
+    "openai_agents",
+    "langgraph",
+    "crewai",
+    "autogen",
+    "openclaw",
+]