dhee 7.2.0__tar.gz → 7.2.3__tar.gz

{dhee-7.2.0/dhee.egg-info → dhee-7.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dhee
-Version: 7.2.0
+Version: 7.2.3
 Summary: Dhee - world memory layer and context compiler for AI agents
 Author: Sankhya AI Labs
 License-Expression: MIT
@@ -38,6 +38,8 @@ Provides-Extra: gemini
 Requires-Dist: google-genai>=1.0.0; extra == "gemini"
 Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: elevenlabs
+Requires-Dist: elevenlabs>=2.49.0; extra == "elevenlabs"
 Provides-Extra: ollama
 Requires-Dist: ollama>=0.4.0; extra == "ollama"
 Provides-Extra: nvidia
@@ -81,6 +83,7 @@ Requires-Dist: ollama>=0.4.0; extra == "app"
 Provides-Extra: all
 Requires-Dist: google-genai>=1.0.0; extra == "all"
 Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: elevenlabs>=2.49.0; extra == "all"
 Requires-Dist: ollama>=0.4.0; extra == "all"
 Requires-Dist: zvec>=0.4.0; python_version >= "3.11" and extra == "all"
 Requires-Dist: mcp>=1.0.0; python_version >= "3.10" and extra == "all"
@@ -108,7 +111,7 @@ Dynamic: license-file
 
 <p align="center">
   <b>World memory for AI agents.</b><br>
-  A context compiler, repo brain, narrative scene graph, handoff bus, and proof layer for Codex, Claude Code, Cursor, Gemini CLI, Cline, Chotu, and any MCP client.
+  A arc based context compiler for ai agents
 </p>
 
 <p align="center">
@@ -274,6 +277,170 @@ A good agent loop is simple:
 bootstrap -> start scene -> gather evidence -> retrieve context -> act -> verify -> end scene -> save digest
 ```
 
+## Agent Runtime
+
+Dhee now plugs into existing agents with a few lines of code.
+
+If you already have an agent, you keep your provider SDK, model, tools, audio interface, callbacks, and deployment. Dhee adds the missing memory loop:
+
+```text
+before run -> inject compact Dhee context
+during run -> expose a dhee_memory tool
+after run  -> checkpoint what should matter next time
+```
+
+Current native integrations:
+
+| Provider | Import | Minimal change |
+| --- | --- | --- |
+| ElevenLabs voice agents | `from dhee import ElevenLabsAgent` | Add Dhee dynamic variables, client tool, callback wrappers, and post-call checkpointing. |
+| Gemini API agents | `from dhee import GeminiAgent` | Pass `config=memory.generate_content_config()` into `client.models.generate_content(...)`. |
+| OpenAI Responses API agents | `from dhee import OpenAIAgent` | Spread `**memory.response_create_kwargs(...)` into `client.responses.create(...)`. |
+
+Dhee can also run as a small HTTP sidecar for agents that cannot use local Python or stdio MCP.
+
+```bash
+export DHEE_HTTP_TOKEN="dev-token"
+export ELEVENLABS_WEBHOOK_SECRET="..."
+dhee serve --host 0.0.0.0 --port 8765 --profile elevenlabs
+```
+
+Unsigned ElevenLabs post-call webhooks are rejected by default; use `--allow-unsigned-webhooks` only for local development.
+
+The universal runtime surface is intentionally provider-neutral:
+
+```python
+import dhee
+
+memory = dhee.Client(user_id="user_123", app_id="elevenlabs:support-agent")
+run = memory.run(task="voice support call")
+patch = run.before(channel="voice")
+run.tool("remember", content="User prefers WhatsApp follow-up.")
+run.finish(summary="User asked about refund status.")
+```
+
+For an existing ElevenLabs voice agent, the minimal native path is:
+
+```python
+from dhee import ElevenLabsAgent
+
+agent = ElevenLabsAgent(
+    public_base_url="https://memory.example.com",
+    user_id="user_123",
+    agent_id="support-agent",
+)
+
+conversation = agent.create_conversation(api_key="...")
+conversation.start_session()
+```
+
+That keeps your ElevenLabs agent, audio interface, and callbacks intact while Dhee adds:
+
+- `ConversationInitiationData(dynamic_variables={...})` with `dhee_context`
+- a native `dhee_memory` client tool
+- transcript event capture through wrapped callbacks
+- post-call checkpoint helpers
+
+If you already construct `Conversation(...)` yourself, make the smaller patch:
+
+```python
+memory = ElevenLabsAgent(
+    public_base_url="https://memory.example.com",
+    user_id="user_123",
+    agent_id=agent_id,
+)
+
+conversation = Conversation(
+    client=elevenlabs,
+    agent_id=agent_id,
+    config=memory.conversation_initiation_data(),
+    client_tools=memory.client_tools(existing_client_tools),
+    callback_user_transcript=memory.wrap_user_transcript(on_user_transcript),
+    callback_agent_response=memory.wrap_agent_response(on_agent_response),
+    audio_interface=audio_interface,
+)
+```
+
+Install the optional SDK bridge with:
+
+```bash
+pip install "dhee[elevenlabs]"
+```
+
+For hosted/server-tool deployment, use the profile helper:
+
+```bash
+dhee elevenlabs init --public-url https://memory.example.com
+```
+
+That prints the dynamic variables, `dhee_memory` server tool, and post-call webhook URL. The flow is:
+
+```text
+call start -> {{dhee_context}}
+during call -> dhee_memory server tool
+call end -> post-call webhook checkpoint
+next call -> better injected context
+```
+
+The native provider lives at [`dhee.providers.elevenlabs`](dhee/providers/elevenlabs.py) and is exported as `dhee.ElevenLabsAgent` and `dhee.ElevenAgent`.
+
+For an existing Gemini API agent, add Dhee to the existing `generate_content` call:
+
+```python
+from google import genai
+from dhee import GeminiAgent
+
+client = genai.Client(api_key="...")
+memory = GeminiAgent(user_id="user_123", model="gemini-2.5-flash")
+
+response = client.models.generate_content(
+    model=memory.model,
+    contents="What did I ask you to remember?",
+    config=memory.generate_content_config(),
+)
+```
+
+The config injects Dhee context as a system instruction and adds `memory.dhee_memory` as a Gemini Python function tool. You can also call through Dhee:
+
+```python
+response = memory.generate_content(
+    "Please remember I prefer concise summaries.",
+    client=client,
+)
+```
+
+The native Gemini provider lives at [`dhee.providers.gemini`](dhee/providers/gemini.py) and is exported as `dhee.GeminiAgent` and `dhee.GeminiAPIAgent`.
+
+For an existing OpenAI Responses API agent, add Dhee to the existing request:
+
+```python
+from openai import OpenAI
+from dhee import OpenAIAgent
+
+client = OpenAI(api_key="...")
+memory = OpenAIAgent(user_id="user_123", model="gpt-4.1")
+
+response = client.responses.create(
+    **memory.response_create_kwargs(
+        input="What should you remember about me?",
+    )
+)
+```
+
+When the model returns `function_call` items, Dhee can execute them and format Responses API tool outputs:
+
+```python
+tool_outputs = memory.function_call_outputs(response)
+followup = client.responses.create(
+    model=memory.model,
+    input=tool_outputs,
+    previous_response_id=response.id,
+    tools=memory.tools(),
+)
+```
+
+The native OpenAI provider lives at [`dhee.providers.openai`](dhee/providers/openai.py) and is exported as `dhee.OpenAIAgent` and `dhee.OpenAIResponsesAgent`.
+
 ## Repo Brain
 
 Ask: "If I touch this file, what breaks?"

{dhee-7.2.0 → dhee-7.2.3}/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <b>World memory for AI agents.</b><br>
-  A context compiler, repo brain, narrative scene graph, handoff bus, and proof layer for Codex, Claude Code, Cursor, Gemini CLI, Cline, Chotu, and any MCP client.
+  A arc based context compiler for ai agents
 </p>
 
 <p align="center">
@@ -172,6 +172,170 @@ A good agent loop is simple:
 bootstrap -> start scene -> gather evidence -> retrieve context -> act -> verify -> end scene -> save digest
 ```
 
+## Agent Runtime
+
+Dhee now plugs into existing agents with a few lines of code.
+
+If you already have an agent, you keep your provider SDK, model, tools, audio interface, callbacks, and deployment. Dhee adds the missing memory loop:
+
+```text
+before run -> inject compact Dhee context
+during run -> expose a dhee_memory tool
+after run  -> checkpoint what should matter next time
+```
+
+Current native integrations:
+
+| Provider | Import | Minimal change |
+| --- | --- | --- |
+| ElevenLabs voice agents | `from dhee import ElevenLabsAgent` | Add Dhee dynamic variables, client tool, callback wrappers, and post-call checkpointing. |
+| Gemini API agents | `from dhee import GeminiAgent` | Pass `config=memory.generate_content_config()` into `client.models.generate_content(...)`. |
+| OpenAI Responses API agents | `from dhee import OpenAIAgent` | Spread `**memory.response_create_kwargs(...)` into `client.responses.create(...)`. |
+
+Dhee can also run as a small HTTP sidecar for agents that cannot use local Python or stdio MCP.
+
+```bash
+export DHEE_HTTP_TOKEN="dev-token"
+export ELEVENLABS_WEBHOOK_SECRET="..."
+dhee serve --host 0.0.0.0 --port 8765 --profile elevenlabs
+```
+
+Unsigned ElevenLabs post-call webhooks are rejected by default; use `--allow-unsigned-webhooks` only for local development.
+
+The universal runtime surface is intentionally provider-neutral:
+
+```python
+import dhee
+
+memory = dhee.Client(user_id="user_123", app_id="elevenlabs:support-agent")
+run = memory.run(task="voice support call")
+patch = run.before(channel="voice")
+run.tool("remember", content="User prefers WhatsApp follow-up.")
+run.finish(summary="User asked about refund status.")
+```
+
+For an existing ElevenLabs voice agent, the minimal native path is:
+
+```python
+from dhee import ElevenLabsAgent
+
+agent = ElevenLabsAgent(
+    public_base_url="https://memory.example.com",
+    user_id="user_123",
+    agent_id="support-agent",
+)
+
+conversation = agent.create_conversation(api_key="...")
+conversation.start_session()
+```
+
+That keeps your ElevenLabs agent, audio interface, and callbacks intact while Dhee adds:
+
+- `ConversationInitiationData(dynamic_variables={...})` with `dhee_context`
+- a native `dhee_memory` client tool
+- transcript event capture through wrapped callbacks
+- post-call checkpoint helpers
+
+If you already construct `Conversation(...)` yourself, make the smaller patch:
+
+```python
+memory = ElevenLabsAgent(
+    public_base_url="https://memory.example.com",
+    user_id="user_123",
+    agent_id=agent_id,
+)
+
+conversation = Conversation(
+    client=elevenlabs,
+    agent_id=agent_id,
+    config=memory.conversation_initiation_data(),
+    client_tools=memory.client_tools(existing_client_tools),
+    callback_user_transcript=memory.wrap_user_transcript(on_user_transcript),
+    callback_agent_response=memory.wrap_agent_response(on_agent_response),
+    audio_interface=audio_interface,
+)
+```
+
+Install the optional SDK bridge with:
+
+```bash
+pip install "dhee[elevenlabs]"
+```
+
+For hosted/server-tool deployment, use the profile helper:
+
+```bash
+dhee elevenlabs init --public-url https://memory.example.com
+```
+
+That prints the dynamic variables, `dhee_memory` server tool, and post-call webhook URL. The flow is:
+
+```text
+call start -> {{dhee_context}}
+during call -> dhee_memory server tool
+call end -> post-call webhook checkpoint
+next call -> better injected context
+```
+
+The native provider lives at [`dhee.providers.elevenlabs`](dhee/providers/elevenlabs.py) and is exported as `dhee.ElevenLabsAgent` and `dhee.ElevenAgent`.
+
+For an existing Gemini API agent, add Dhee to the existing `generate_content` call:
+
+```python
+from google import genai
+from dhee import GeminiAgent
+
+client = genai.Client(api_key="...")
+memory = GeminiAgent(user_id="user_123", model="gemini-2.5-flash")
+
+response = client.models.generate_content(
+    model=memory.model,
+    contents="What did I ask you to remember?",
+    config=memory.generate_content_config(),
+)
+```
+
+The config injects Dhee context as a system instruction and adds `memory.dhee_memory` as a Gemini Python function tool. You can also call through Dhee:
+
+```python
+response = memory.generate_content(
+    "Please remember I prefer concise summaries.",
+    client=client,
+)
+```
+
+The native Gemini provider lives at [`dhee.providers.gemini`](dhee/providers/gemini.py) and is exported as `dhee.GeminiAgent` and `dhee.GeminiAPIAgent`.
+
+For an existing OpenAI Responses API agent, add Dhee to the existing request:
+
+```python
+from openai import OpenAI
+from dhee import OpenAIAgent
+
+client = OpenAI(api_key="...")
+memory = OpenAIAgent(user_id="user_123", model="gpt-4.1")
+
+response = client.responses.create(
+    **memory.response_create_kwargs(
+        input="What should you remember about me?",
+    )
+)
+```
+
+When the model returns `function_call` items, Dhee can execute them and format Responses API tool outputs:
+
+```python
+tool_outputs = memory.function_call_outputs(response)
+followup = client.responses.create(
+    model=memory.model,
+    input=tool_outputs,
+    previous_response_id=response.id,
+    tools=memory.tools(),
+)
+```
+
+The native OpenAI provider lives at [`dhee.providers.openai`](dhee/providers/openai.py) and is exported as `dhee.OpenAIAgent` and `dhee.OpenAIResponsesAgent`.
+
 ## Repo Brain
 
 Ask: "If I touch this file, what breaks?"

{dhee-7.2.0 → dhee-7.2.3}/dhee/__init__.py

@@ -26,6 +26,15 @@ from dhee.memory.smart import SmartMemory
 from dhee.memory.main import FullMemory
 from dhee.simple import Dhee, Engram
 from dhee.plugin import DheePlugin
+from dhee.agent_runtime import Client, Run, Patch
+from dhee.providers import (
+    ElevenAgent,
+    ElevenLabsAgent,
+    GeminiAgent,
+    GeminiAPIAgent,
+    OpenAIAgent,
+    OpenAIResponsesAgent,
+)
 from dhee.fs import ContextWorkspace
 from dhee.context_kernel import DheeContextKernel, KernelScope
 from dhee.core.category import CategoryProcessor, Category, CategoryType, CategoryMatch
@@ -41,7 +50,7 @@ from dhee.memory.admission import (
 # Default import remains model-free for backwards compatibility.
 Memory = CoreMemory
 
-__version__ = "7.2.0"
+__version__ = "7.2.3"
 __all__ = [
     # Memory classes
     "Engram",
@@ -53,6 +62,16 @@ __all__ = [
     "Dhee",
     # Universal plugin
     "DheePlugin",
+    # Universal agent runtime
+    "Client",
+    "Run",
+    "Patch",
+    "ElevenAgent",
+    "ElevenLabsAgent",
+    "GeminiAgent",
+    "GeminiAPIAgent",
+    "OpenAIAgent",
+    "OpenAIResponsesAgent",
     # DheeFS
     "ContextWorkspace",
     "DheeContextKernel",

dhee-7.2.3/dhee/agent_runtime/__init__.py

@@ -0,0 +1,9 @@
+"""Universal agent runtime for Dhee."""
+
+from __future__ import annotations
+
+from dhee.agent_runtime.client import Client
+from dhee.agent_runtime.models import Patch, ToolResult
+from dhee.agent_runtime.run import Run
+
+__all__ = ["Client", "Run", "Patch", "ToolResult"]

dhee-7.2.3/dhee/agent_runtime/auth.py

@@ -0,0 +1,22 @@
+"""HTTP auth helpers for the Dhee agent runtime sidecar."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from fastapi import HTTPException
+
+
+def require_bearer_token(authorization: Optional[str], token: Optional[str] = None) -> None:
+    """Validate bearer auth when a sidecar token is configured."""
+
+    expected = token if token is not None else os.getenv("DHEE_HTTP_TOKEN")
+    if not expected:
+        return
+    prefix = "Bearer "
+    if not authorization or not authorization.startswith(prefix):
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+    supplied = authorization[len(prefix) :].strip()
+    if supplied != expected:
+        raise HTTPException(status_code=401, detail="Invalid bearer token")

dhee-7.2.3/dhee/agent_runtime/client.py

@@ -0,0 +1,51 @@
+"""Python SDK entry point for Dhee's universal agent runtime."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from dhee.agent_runtime.run import Run
+from dhee.plugin import DheePlugin
+
+
+class Client:
+    """Small framework-neutral runtime client.
+
+    This is intentionally not an ElevenLabs, Gemini, or OpenAI client. It only
+    translates agent lifecycle events into Dhee's existing cognition plugin.
+    """
+
+    def __init__(
+        self,
+        user_id: str = "default",
+        app_id: str = "default-agent",
+        data_dir: Optional[Union[str, Path]] = None,
+        provider: Optional[str] = None,
+        in_memory: bool = False,
+        offline: bool = False,
+    ):
+        self.user_id = user_id
+        self.app_id = app_id
+        self.plugin = DheePlugin(
+            user_id=user_id,
+            data_dir=data_dir,
+            provider=provider,
+            in_memory=in_memory,
+            offline=offline,
+        )
+
+    def run(
+        self,
+        task: Optional[str] = None,
+        run_id: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> Run:
+        return Run(
+            plugin=self.plugin,
+            user_id=self.user_id,
+            app_id=self.app_id,
+            task=task,
+            run_id=run_id,
+            metadata=metadata or {},
+        )

dhee-7.2.3/dhee/agent_runtime/events.py

@@ -0,0 +1,10 @@
+"""Event names used by the universal agent runtime."""
+
+from __future__ import annotations
+
+
+VOICE_USER_TRANSCRIPT = "voice.user_transcript"
+VOICE_AGENT_RESPONSE = "voice.agent_response"
+VOICE_CALL_SUMMARY = "voice.call_summary"
+VOICE_FOLLOWUP = "voice.followup"
+VOICE_CORRECTION = "voice.correction"

dhee-7.2.3/dhee/agent_runtime/models.py

@@ -0,0 +1,26 @@
+"""Pydantic models for Dhee's universal agent runtime."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Patch(BaseModel):
+    """Context patch returned before an agent run starts."""
+
+    run_id: str
+    user_id: str
+    app_id: str
+    context: str
+    dynamic_variables: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(BaseModel):
+    """Voice- and agent-friendly result from the memory tool surface."""
+
+    ok: bool = True
+    speakable_summary: Optional[str] = None
+    result: dict[str, Any] = Field(default_factory=dict)

dhee-7.2.3/dhee/agent_runtime/policy.py

@@ -0,0 +1,89 @@
+"""Admission and redaction policy for voice-agent memory events."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+SECRET_PATTERNS = [
+    re.compile(r"\b\d{6}\b"),
+    re.compile(r"(?i)\b(password|passcode|api key|secret|token)\b[:\s]+[^\s,.;]+"),
+    re.compile(r"\b(?:\d[ -]*?){13,19}\b"),
+]
+
+
+@dataclass
+class Admission:
+    should_store: bool
+    content: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    reason: str = ""
+
+
+def contains_voice_secret(content: str) -> bool:
+    """Return True when text contains data Dhee should not retain."""
+
+    text = content or ""
+    return any(pattern.search(text) for pattern in SECRET_PATTERNS)
+
+
+def redact_voice_content(content: str) -> str:
+    """Redact high-risk voice content before it can enter memory."""
+
+    text = content or ""
+    for pattern in SECRET_PATTERNS:
+        text = pattern.sub("[REDACTED]", text)
+    return text
+
+
+def admit_voice_event(event: dict[str, Any]) -> Admission:
+    """Decide whether a noisy voice event is worth storing."""
+
+    event_type = str(event.get("type") or "")
+    content = str(event.get("content") or "").strip()
+    lowered = content.lower()
+
+    if not content:
+        return Admission(False, reason="empty")
+
+    if contains_voice_secret(content):
+        return Admission(False, reason="sensitive_content")
+
+    durable_markers = [
+        "remember",
+        "i prefer",
+        "my preference",
+        "next time",
+        "follow up",
+        "call me",
+        "message me",
+        "whatsapp",
+        "email me",
+        "i decided",
+        "we decided",
+        "correct that",
+        "actually",
+        "my name is",
+        "don't ask me",
+        "do not ask me",
+    ]
+
+    if any(marker in lowered for marker in durable_markers):
+        return Admission(
+            True,
+            content=redact_voice_content(content),
+            metadata={"retention_policy": "durable", "channel": "voice"},
+            reason="durable_voice_marker",
+        )
+
+    if event_type in {"voice.call_summary", "voice.followup", "voice.correction"}:
+        return Admission(
+            True,
+            content=redact_voice_content(content),
+            metadata={"retention_policy": "durable", "channel": "voice"},
+            reason=event_type,
+        )
+
+    return Admission(False, reason="voice_noise")