voxinfra 0.1.0__tar.gz

voxinfra-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: voxinfra
+Version: 0.1.0
+Summary: Production infrastructure for voice agents — memory, tool orchestration, and observability
+Author: Ashu Singhania
+License: MIT
+Keywords: voice,agent,livekit,memory,observability,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mem0ai>=0.1.0
+Requires-Dist: livekit-agents>=1.5.0
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: opentelemetry-api>=1.24.0
+Requires-Dist: supabase>=2.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+
+# VoxInfra
+
+Production memory, tool safety, and call replay for LiveKit voice agents.
+
+---
+
+## The Problem
+
+- **No memory** — Your agent forgets users the moment the call ends, making every interaction feel cold and repetitive.
+- **Latency kills** — A single CRM lookup timing out can freeze the audio stream and drop the call.
+- **No replay** — When a call goes wrong, you have no structured trace to debug what the agent heard, recalled, or decided.
+
+---
+
+## Install
+
+```bash
+pip install voxinfra
+```
+
+---
+
+## Quick Start
+
+```python
+from dotenv import load_dotenv
+from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
+from livekit.plugins import deepgram, elevenlabs, openai, silero
+from voxinfra import VoxSession, vox_tool
+
+load_dotenv()
+vox = VoxSession()  # reads MEM0_API_KEY, SUPABASE_URL from env
+
+@vox_tool(sla_ms=200, fallback={"name": "there"})
+async def get_user_info(user_id: str) -> dict:
+    return await crm.lookup(user_id)
+
+class MyAgent(Agent):
+    async def on_enter(self):
+        call_id = str(__import__("uuid").uuid4())
+        self.session.userdata["call_id"] = call_id
+        vox.obs.start_call(call_id, self.session.userdata["user_id"])
+
+    async def on_exit(self):
+        await vox.end_call(self.session.userdata["call_id"])
+
+    async def llm_node(self, chat_ctx, tools, model_settings):
+        user_id = self.session.userdata["user_id"]
+        call_id = self.session.userdata["call_id"]
+        async with vox.turn(user_id=user_id, chat_ctx=chat_ctx, call_id=call_id) as turn:
+            await turn.call_tool(get_user_info, user_id)
+            return await turn.run_llm(tools, model_settings)
+```
+
+---
+
+## VoxMemory
+
+Persistent cross-call memory backed by [Mem0](https://mem0.ai) (hosted) or Qdrant (self-hosted). At the start of every turn, VoxInfra semantically searches past conversations and injects the top results into the LLM context — automatically, in 3 lines or fewer to keep voice prompts lean.
+
+```python
+# Automatic via vox.turn() — no extra code needed
+async with vox.turn(user_id="u-123", chat_ctx=chat_ctx, call_id=call_id) as turn:
+    # Memory was recalled and injected before this line
+    return await turn.run_llm(tools, model_settings)
+
+# Manual DPDP right-to-erasure
+await vox.memory.delete_user("u-123")
+```
+
+---
+
+## VoxTools
+
+A registry of async tools with per-tool SLA enforcement. If a tool exceeds its SLA, VoxInfra serves a cached result or fallback — the agent keeps talking and the call never drops.
+
+```python
+@vox_tool(sla_ms=200, fallback={"status": "unavailable"})
+async def get_appointments(user_id: str) -> dict:
+    return await calendar_api.fetch(user_id)
+
+# Inside llm_node
+async with vox.turn(...) as turn:
+    # If get_appointments takes >200ms, fallback is returned silently
+    result = await turn.call_tool(get_appointments, user_id)
+```
+
+The `@vox_tool` decorator is transparent — it only attaches metadata. The function remains directly callable without going through VoxTools.
+
+---
+
+## VoxObs
+
+Structured call traces persisted to a Supabase table (`vox_call_traces`). Every turn records user transcript, memory recall latency, LLM latency, TTS latency, and all tool call results with SLA breach flags. Use `vox.end_call()` to finalise and flush the trace.
+
+```python
+# In Agent.on_exit
+await vox.end_call(self.session.userdata["call_id"])
+```
+
+The Supabase write is always fire-and-forget — it never blocks the call path.
+
+---
+
+## Config
+
+All configuration via environment variables or constructor kwargs.
+
+| Variable | Description | Required |
+|---|---|---|
+| `MEM0_API_KEY` | Mem0 hosted API key | Yes (mem0 backend) |
+| `QDRANT_URL` | Qdrant server URL | Yes (qdrant backend) |
+| `QDRANT_API_KEY` | Qdrant API key | No |
+| `SUPABASE_URL` | Supabase project URL | No (obs disabled without it) |
+| `SUPABASE_SERVICE_KEY` | Supabase service role key | No |
+| `VOXINFRA_API_KEY` | Reserved for future cloud features | No |
+
+```python
+# From env (default)
+vox = VoxSession()
+
+# Explicit
+vox = VoxSession(
+    mem0_api_key="m0-...",
+    supabase_url="https://xyz.supabase.co",
+    supabase_key="service-key",
+    default_tool_sla_ms=250,
+)
+
+# Qdrant backend (self-hosted)
+vox = VoxSession(
+    memory_backend="qdrant",
+    qdrant_url="http://localhost:6333",
+    qdrant_collection="my_agent_memories",
+)
+```
+
+---
+
+## DPDP Compliance
+
+For deployments subject to India's Digital Personal Data Protection Act, VoxInfra supports a fully self-hosted data path. Use the Qdrant backend pointed at a Mumbai-region instance to ensure all memory vectors stay within Indian jurisdiction. Call traces can be stored in a Supabase project provisioned in the `ap-south-1` region. Users have the right to erasure under DPDP Section 13 — invoke it with a single call:
+
+```python
+await vox.memory.delete_user(user_id)
+```
+
+This calls Mem0's `delete_all` or Qdrant's collection filter delete under the hood, removing all stored memories for that user permanently.
+
+---
+
+## License
+
+MIT © Ashu Singhania

voxinfra-0.1.0/README.md

@@ -0,0 +1,154 @@
+# VoxInfra
+
+Production memory, tool safety, and call replay for LiveKit voice agents.
+
+---
+
+## The Problem
+
+- **No memory** — Your agent forgets users the moment the call ends, making every interaction feel cold and repetitive.
+- **Latency kills** — A single CRM lookup timing out can freeze the audio stream and drop the call.
+- **No replay** — When a call goes wrong, you have no structured trace to debug what the agent heard, recalled, or decided.
+
+---
+
+## Install
+
+```bash
+pip install voxinfra
+```
+
+---
+
+## Quick Start
+
+```python
+from dotenv import load_dotenv
+from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
+from livekit.plugins import deepgram, elevenlabs, openai, silero
+from voxinfra import VoxSession, vox_tool
+
+load_dotenv()
+vox = VoxSession()  # reads MEM0_API_KEY, SUPABASE_URL from env
+
+@vox_tool(sla_ms=200, fallback={"name": "there"})
+async def get_user_info(user_id: str) -> dict:
+    return await crm.lookup(user_id)
+
+class MyAgent(Agent):
+    async def on_enter(self):
+        call_id = str(__import__("uuid").uuid4())
+        self.session.userdata["call_id"] = call_id
+        vox.obs.start_call(call_id, self.session.userdata["user_id"])
+
+    async def on_exit(self):
+        await vox.end_call(self.session.userdata["call_id"])
+
+    async def llm_node(self, chat_ctx, tools, model_settings):
+        user_id = self.session.userdata["user_id"]
+        call_id = self.session.userdata["call_id"]
+        async with vox.turn(user_id=user_id, chat_ctx=chat_ctx, call_id=call_id) as turn:
+            await turn.call_tool(get_user_info, user_id)
+            return await turn.run_llm(tools, model_settings)
+```
+
+---
+
+## VoxMemory
+
+Persistent cross-call memory backed by [Mem0](https://mem0.ai) (hosted) or Qdrant (self-hosted). At the start of every turn, VoxInfra semantically searches past conversations and injects the top results into the LLM context — automatically, in 3 lines or fewer to keep voice prompts lean.
+
+```python
+# Automatic via vox.turn() — no extra code needed
+async with vox.turn(user_id="u-123", chat_ctx=chat_ctx, call_id=call_id) as turn:
+    # Memory was recalled and injected before this line
+    return await turn.run_llm(tools, model_settings)
+
+# Manual DPDP right-to-erasure
+await vox.memory.delete_user("u-123")
+```
+
+---
+
+## VoxTools
+
+A registry of async tools with per-tool SLA enforcement. If a tool exceeds its SLA, VoxInfra serves a cached result or fallback — the agent keeps talking and the call never drops.
+
+```python
+@vox_tool(sla_ms=200, fallback={"status": "unavailable"})
+async def get_appointments(user_id: str) -> dict:
+    return await calendar_api.fetch(user_id)
+
+# Inside llm_node
+async with vox.turn(...) as turn:
+    # If get_appointments takes >200ms, fallback is returned silently
+    result = await turn.call_tool(get_appointments, user_id)
+```
+
+The `@vox_tool` decorator is transparent — it only attaches metadata. The function remains directly callable without going through VoxTools.
+
+---
+
+## VoxObs
+
+Structured call traces persisted to a Supabase table (`vox_call_traces`). Every turn records user transcript, memory recall latency, LLM latency, TTS latency, and all tool call results with SLA breach flags. Use `vox.end_call()` to finalise and flush the trace.
+
+```python
+# In Agent.on_exit
+await vox.end_call(self.session.userdata["call_id"])
+```
+
+The Supabase write is always fire-and-forget — it never blocks the call path.
+
+---
+
+## Config
+
+All configuration via environment variables or constructor kwargs.
+
+| Variable | Description | Required |
+|---|---|---|
+| `MEM0_API_KEY` | Mem0 hosted API key | Yes (mem0 backend) |
+| `QDRANT_URL` | Qdrant server URL | Yes (qdrant backend) |
+| `QDRANT_API_KEY` | Qdrant API key | No |
+| `SUPABASE_URL` | Supabase project URL | No (obs disabled without it) |
+| `SUPABASE_SERVICE_KEY` | Supabase service role key | No |
+| `VOXINFRA_API_KEY` | Reserved for future cloud features | No |
+
+```python
+# From env (default)
+vox = VoxSession()
+
+# Explicit
+vox = VoxSession(
+    mem0_api_key="m0-...",
+    supabase_url="https://xyz.supabase.co",
+    supabase_key="service-key",
+    default_tool_sla_ms=250,
+)
+
+# Qdrant backend (self-hosted)
+vox = VoxSession(
+    memory_backend="qdrant",
+    qdrant_url="http://localhost:6333",
+    qdrant_collection="my_agent_memories",
+)
+```
+
+---
+
+## DPDP Compliance
+
+For deployments subject to India's Digital Personal Data Protection Act, VoxInfra supports a fully self-hosted data path. Use the Qdrant backend pointed at a Mumbai-region instance to ensure all memory vectors stay within Indian jurisdiction. Call traces can be stored in a Supabase project provisioned in the `ap-south-1` region. Users have the right to erasure under DPDP Section 13 — invoke it with a single call:
+
+```python
+await vox.memory.delete_user(user_id)
+```
+
+This calls Mem0's `delete_all` or Qdrant's collection filter delete under the hood, removing all stored memories for that user permanently.
+
+---
+
+## License
+
+MIT © Ashu Singhania

voxinfra-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voxinfra"
+version = "0.1.0"
+description = "Production infrastructure for voice agents — memory, tool orchestration, and observability"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Ashu Singhania" }]
+keywords = ["voice", "agent", "livekit", "memory", "observability", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "mem0ai>=0.1.0",
+    "livekit-agents>=1.5.0",
+    "opentelemetry-sdk>=1.24.0",
+    "opentelemetry-api>=1.24.0",
+    "supabase>=2.4.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.6.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3.12",
+    "ruff>=0.4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["voxinfra*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

voxinfra-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

voxinfra-0.1.0/tests/test_memory.py

@@ -0,0 +1,81 @@
+import asyncio
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from voxinfra.config import VoxConfig
+from voxinfra.memory import VoxMemory
+
+
+def make_memory(mem0_api_key: str = "test-key") -> VoxMemory:
+    """Build a VoxMemory with a mocked MemoryClient."""
+    config = VoxConfig(mem0_api_key=mem0_api_key, memory_backend="mem0")
+    mock_client = MagicMock()
+    # Patch both the module-level name and the mem0 package import path
+    with patch("voxinfra.memory.MemoryClient", return_value=mock_client):
+        mem = VoxMemory(config)
+    # Replace client directly in case patching resolved differently
+    mem._client = mock_client
+    return mem
+
+
+@pytest.mark.asyncio
+async def test_recall_returns_empty_on_no_memories() -> None:
+    mem = make_memory()
+    mem._client.search = MagicMock(return_value=[])
+    snippet, latency_ms, count = await mem.recall("user-1", "some context")
+    assert snippet == ""
+    assert latency_ms >= 0.0
+    assert count == 0
+
+
+@pytest.mark.asyncio
+async def test_recall_formats_memories_correctly() -> None:
+    mem = make_memory()
+    mem._client.search = MagicMock(
+        return_value=[
+            {"memory": "User prefers Hindi", "score": 0.95},
+            {"memory": "Has diabetes", "score": 0.88},
+        ]
+    )
+    snippet, latency_ms, count = await mem.recall("user-1", "health preferences")
+    assert "User prefers Hindi" in snippet
+    assert "Has diabetes" in snippet
+    assert count == 2
+
+
+@pytest.mark.asyncio
+async def test_recall_never_raises_on_exception() -> None:
+    mem = make_memory()
+    mem._client.search = MagicMock(side_effect=RuntimeError("network error"))
+    snippet, latency_ms, count = await mem.recall("user-1", "anything")
+    assert snippet == ""
+    assert latency_ms == 0.0
+    assert count == 0
+
+
+@pytest.mark.asyncio
+async def test_store_is_fire_and_forget() -> None:
+    mem = make_memory()
+    add_called = asyncio.Event()
+
+    def fake_add(**kwargs):
+        add_called.set()
+        return None
+
+    mem._client.add = MagicMock(side_effect=fake_add)
+
+    # store() should return immediately without blocking
+    await mem.store("user-1", "some transcript")
+
+    # Give the background task a moment to run
+    await asyncio.sleep(0.05)
+    assert add_called.is_set(), "add() should have been called via background task"
+
+
+@pytest.mark.asyncio
+async def test_delete_user_calls_delete_all() -> None:
+    mem = make_memory()
+    mem._client.delete_all = MagicMock(return_value=None)
+    await mem.delete_user("user-123")
+    mem._client.delete_all.assert_called_once_with(user_id="user-123")

voxinfra-0.1.0/tests/test_obs.py

@@ -0,0 +1,83 @@
+import pytest
+
+from voxinfra.config import VoxConfig
+from voxinfra.models import ToolResult, TurnTrace
+from voxinfra.obs import VoxObs
+
+
+def make_obs() -> VoxObs:
+    config = VoxConfig(mem0_api_key="test-key", obs_enabled=False)
+    return VoxObs(config)
+
+
+def make_turn(call_id: str, turn_number: int, total_turn_ms: float = 0.0) -> TurnTrace:
+    return TurnTrace(call_id=call_id, turn_number=turn_number, user_transcript="hello", total_turn_ms=total_turn_ms)
+
+
+def test_start_call_creates_trace() -> None:
+    obs = make_obs()
+    obs.start_call("call-1", "user-1")
+    trace = obs.get_call("call-1")
+    assert trace is not None
+    assert trace.user_id == "user-1"
+
+
+@pytest.mark.asyncio
+async def test_turns_accumulate_correctly() -> None:
+    obs = make_obs()
+    obs.start_call("call-2", "user-2")
+    for i in range(1, 4):
+        turn = obs.start_turn("call-2", f"turn {i}")
+        obs.finish_turn("call-2", turn)
+    call = await obs.finish_call("call-2")
+    assert call is not None
+    assert call.total_turns == 3
+    assert len(call.turns) == 3
+
+
+@pytest.mark.asyncio
+async def test_avg_turn_ms_computed_correctly() -> None:
+    obs = make_obs()
+    obs.start_call("call-3", "user-3")
+    for ms in [100.0, 200.0, 300.0]:
+        turn = make_turn("call-3", 1, total_turn_ms=ms)
+        obs.finish_turn("call-3", turn)
+    call = await obs.finish_call("call-3")
+    assert call is not None
+    assert call.avg_turn_ms == pytest.approx(200.0)
+
+
+@pytest.mark.asyncio
+async def test_sla_breach_count_computed_correctly() -> None:
+    obs = make_obs()
+    obs.start_call("call-4", "user-4")
+
+    def make_tool(breached: bool) -> ToolResult:
+        return ToolResult(
+            tool_name="t",
+            success=True,
+            latency_ms=10.0,
+            sla_ms=300,
+            sla_breached=breached,
+            used_fallback=False,
+        )
+
+    turn1 = make_turn("call-4", 1)
+    turn1.tool_results = [make_tool(True), make_tool(True)]
+    obs.finish_turn("call-4", turn1)
+
+    turn2 = make_turn("call-4", 2)
+    turn2.tool_results = [make_tool(False)]
+    obs.finish_turn("call-4", turn2)
+
+    call = await obs.finish_call("call-4")
+    assert call is not None
+    assert call.sla_breach_count == 2
+
+
+@pytest.mark.asyncio
+async def test_finish_call_removes_from_active() -> None:
+    obs = make_obs()
+    obs.start_call("call-5", "user-5")
+    await obs.finish_call("call-5")
+    assert obs.get_call("call-5") is None

voxinfra-0.1.0/tests/test_tools.py

@@ -0,0 +1,89 @@
+import asyncio
+from unittest.mock import MagicMock
+
+import pytest
+
+from voxinfra.config import VoxConfig
+from voxinfra.tools import VoxTools
+
+
+def make_tools(default_sla_ms: int = 300) -> VoxTools:
+    config = VoxConfig(mem0_api_key="test-key", default_tool_sla_ms=default_sla_ms)
+    return VoxTools(config)
+
+
+@pytest.mark.asyncio
+async def test_fast_tool_returns_result() -> None:
+    tools = make_tools()
+
+    async def fast_tool(x: int) -> int:
+        await asyncio.sleep(0.01)
+        return x * 2
+
+    result = await tools.call(fast_tool, 5)
+    assert result.success is True
+    assert result.sla_breached is False
+    assert result.used_fallback is False
+    assert result.result == 10
+
+
+@pytest.mark.asyncio
+async def test_slow_tool_uses_fallback() -> None:
+    tools = make_tools()
+    fallback = {"status": "cached"}
+
+    async def slow_tool() -> dict:
+        await asyncio.sleep(0.5)
+        return {"status": "ok"}
+
+    tools.register(slow_tool, sla_ms=100, fallback=fallback)
+    result = await tools.call(slow_tool)
+    assert result.sla_breached is True
+    assert result.used_fallback is True
+    assert result.result == fallback
+
+
+@pytest.mark.asyncio
+async def test_slow_tool_uses_cache_before_fallback() -> None:
+    tools = make_tools()
+    cached_value = {"data": "from_cache"}
+    fallback = {"data": "fallback"}
+
+    async def slow_tool() -> dict:
+        await asyncio.sleep(0.5)
+        return {"data": "fresh"}
+
+    tools.register(slow_tool, sla_ms=100, fallback=fallback)
+    # Pre-populate cache
+    tools._registry["slow_tool"]["cache"]["slow_tool:some_key"] = cached_value
+
+    result = await tools.call(slow_tool)
+    assert result.sla_breached is True
+    assert result.used_fallback is True
+    assert result.result == cached_value  # cache wins over fallback
+
+
+@pytest.mark.asyncio
+async def test_failing_tool_returns_error_result() -> None:
+    tools = make_tools()
+
+    async def broken_tool() -> dict:
+        raise ValueError("CRM is down")
+
+    tools.register(broken_tool, sla_ms=300, fallback=None)
+    result = await tools.call(broken_tool)
+    assert result.success is False
+    assert result.error is not None
+
+
+@pytest.mark.asyncio
+async def test_call_never_raises() -> None:
+    tools = make_tools()
+
+    async def extreme_failure() -> None:
+        raise SystemExit("chaos")
+
+    tools.register(extreme_failure, sla_ms=300, fallback=None)
+    # Must not propagate any exception
+    result = await tools.call(extreme_failure)
+    assert result.success is False

voxinfra-0.1.0/voxinfra/__init__.py

@@ -0,0 +1,13 @@
+from voxinfra.session import VoxSession
+from voxinfra.memory import VoxMemory
+from voxinfra.tools import VoxTools, vox_tool
+from voxinfra.obs import VoxObs
+from voxinfra.config import VoxConfig
+from voxinfra.models import CallTrace, TurnTrace, ToolResult, MemoryEntry
+
+__all__ = [
+    "VoxSession", "VoxMemory", "VoxTools", "vox_tool",
+    "VoxObs", "VoxConfig", "CallTrace", "TurnTrace", "ToolResult", "MemoryEntry",
+]
+
+__version__ = "0.1.0"

voxinfra-0.1.0/voxinfra/config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+import os
+from dataclasses import dataclass, field
+from typing import Literal
+
+@dataclass
+class VoxConfig:
+    api_key: str = field(default_factory=lambda: os.getenv("VOXINFRA_API_KEY", ""))
+    mem0_api_key: str = field(default_factory=lambda: os.getenv("MEM0_API_KEY", ""))
+    memory_backend: Literal["mem0", "qdrant"] = "mem0"
+    qdrant_url: str = field(default_factory=lambda: os.getenv("QDRANT_URL", "http://localhost:6333"))
+    qdrant_api_key: str = field(default_factory=lambda: os.getenv("QDRANT_API_KEY", ""))
+    qdrant_collection: str = "voxinfra_memories"
+    memory_top_k: int = 5
+    supabase_url: str = field(default_factory=lambda: os.getenv("SUPABASE_URL", ""))
+    supabase_key: str = field(default_factory=lambda: os.getenv("SUPABASE_SERVICE_KEY", ""))
+    obs_enabled: bool = True
+    default_tool_sla_ms: int = 300
+    full_trace_retention_days: int = 7
+    summary_retention_days: int = 90
+
+    def validate(self) -> None:
+        if self.memory_backend == "mem0" and not self.mem0_api_key:
+            raise ValueError("MEM0_API_KEY is required when memory_backend='mem0'.")
+        if self.memory_backend == "qdrant" and not self.qdrant_url:
+            raise ValueError("qdrant_url is required when memory_backend='qdrant'.")
+
+    @classmethod
+    def from_env(cls) -> "VoxConfig":
+        return cls()