memoair-vapi 0.1.0__tar.gz

memoair_vapi-0.1.0/.gitignore

@@ -0,0 +1,198 @@
+# ============================================
+# External dependencies (vendored)
+# ============================================
+/mem0/
+/graphiti/
+/HippoRAG/
+/memvid/
+/PageIndex/
+/NornicDB/
+/cognee/
+
+# ============================================
+# Legacy directories (removed, ignore local copies)
+# ============================================
+/memory-service/
+/home-page/
+/extensionV2/
+
+# ============================================
+# Python virtual environments
+# ============================================
+memory-service-v2/.venv/
+doc-parser/.venv/
+.venv/
+venv/
+env/
+ENV/
+
+# ============================================
+# Environment files (contain secrets)
+# ============================================
+# Ignore all .env files except .env.example
+.env
+.env.voice.local
+.env.local
+.env.*.local
+!.env.example
+!**/.env.example
+
+# ============================================
+# Node.js
+# ============================================
+node_modules/
+extension/node_modules/
+dashboard/node_modules/
+homePage/node_modules/
+home-page/node_modules/
+mcp-server/node_modules/
+
+# ============================================
+# Backend (Go)
+# ============================================
+backend/uploads/
+backend/vendor/
+backend/backend
+backend/server
+backend/*.test
+backend/notetaker.db
+backend/notetaker.db-shm
+backend/notetaker.db-wal
+backend/tmp/
+backend/build-errors.log
+
+# ============================================
+# Next.js / React build output
+# ============================================
+.next/
+out/
+dist/
+build/
+
+# TypeScript incremental build info (regenerated on every tsc run)
+*.tsbuildinfo
+
+# ============================================
+# Extension build output
+# ============================================
+extension/dist/
+extension/dist-extension/
+extension/.next/
+
+# ============================================
+# MCP server build output
+# ============================================
+mcp-server/dist/
+
+# ============================================
+# OS files
+# ============================================
+.DS_Store
+Thumbs.db
+
+# ============================================
+# IDE files
+# ============================================
+.vscode/
+.idea/
+*.swp
+*~
+
+# ============================================
+# Python
+# ============================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.eggs/
+
+# ============================================
+# Logs
+# ============================================
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# ============================================
+# Temp files
+# ============================================
+*.tmp
+*.temp
+.cache/
+
+# ============================================
+# Database files (local dev)
+# ============================================
+*.db
+*.db-shm
+*.db-wal
+!memory-service-v2/.gitkeep
+
+# ============================================
+# Benchmark data (downloaded, large files)
+# ============================================
+memory-service-v2/benchmarks/data/memorybench_large.json
+memory-service-v2/benchmarks/data/*.json
+!memory-service-v2/benchmarks/data/notes.json
+memory-service-v2/benchmarks/results/*.json
+!memory-service-v2/benchmarks/results/baseline.json
+memory-service-v2/.env
+
+# ============================================
+# Rust / memvid-service local config
+# ============================================
+memvid-service/.config/
+
+# Generated benchmark data (large / reproducible)
+memorybench/data/benchmarks/locomo/locomo10-entities.json
+memorybench/data/benchmarks/longmemeval/
+
+# Go test binaries
+backend/service.test
+
+# Debug logs (runtime instrumentation)
+backend/debug_logs/
+
+# OpenMemory - IDE/Assistant specific rules
+.cursor/rules/openmemory.mdc
+
+# MemoAir agent scratch pad (ephemeral, never commit)
+.memoair/
+
+# Spec Kit (project-local config, regenerable via `specify init`)
+.specify/
+
+# Git worktrees (isolated workspaces for parallel feature work)
+.worktrees/
+CLAUDE.md
+AGENTS.md
+
+# ============================================
+# Generated caches (code-review-graph tool output; fully regenerable)
+# ============================================
+graphify-out/
+.graphify-scopes/
+
+# ============================================
+# Runtime / notebook artifacts (never commit)
+# ============================================
+dump.rdb
+v3_store.json
+v3_artifacts/
+
+# voice-runtime build artifacts
+voice-runtime/target/
+.claude/worktrees/
+memory-service-v2/data/permanent_store/
+voice-runtime/dist/
+
+# Secrets / account recovery codes — NEVER commit these
+PyPI-Recovery-Codes*.txt
+*recovery-codes*.txt
+*.pem
+*.key

memoair_vapi-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: memoair-vapi
+Version: 0.1.0
+Summary: VAPI Custom Knowledge Base integration for MemoAir voice memory
+Project-URL: Homepage, https://memoair.dev
+Project-URL: Documentation, https://docs.memoair.dev/voice/integrations/vapi
+Project-URL: Repository, https://github.com/memoair/memoair-python
+Author-email: MemoAir <hello@memoair.dev>
+License-Expression: MIT
+Keywords: agents,ai,memoair,memory,vapi,voice,voice-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: memoair-voice>=0.3.2
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# memoair-vapi
+
+Serve [VAPI's Custom Knowledge Base webhook](https://docs.vapi.ai/knowledge-base/custom-knowledge-base)
+from MemoAir voice memory. Phase 1 retrieves from the shared org index.
+
+## Install
+
+```bash
+pip install memoair-vapi
+```
+
+## Quick start
+
+```python
+import json
+
+from memoair_vapi import MemoAirVapiSearch, verify_vapi_signature
+
+search = MemoAirVapiSearch(
+    api_key="memoair_pk_...",
+    project_id="proj_xxx",
+    agent_id="agent_xxx",
+    top_k=5,
+)
+
+# In your webhook handler (raw_body = exact request bytes):
+if not verify_vapi_signature(raw_body, signature_header, secret):
+    ...  # return 401
+
+payload = json.loads(raw_body)
+documents = await search.handle_request(payload)  # -> {"documents": [...]}
+```
+
+`handle_request` dispatches on `message.type`: `knowledge-base-request` returns
+documents; any other type is acked with `{}`. A malformed knowledge-base request
+raises `VapiWebhookError` (map it to HTTP 400). Retrieval failures degrade to
+`{"documents": []}` so a live call never breaks.
+
+A runnable FastAPI server is in [`examples/vapi/`](../../examples/vapi/).
+
+## Docs
+
+https://docs.memoair.dev/voice/integrations/vapi

memoair_vapi-0.1.0/README.md

@@ -0,0 +1,43 @@
+# memoair-vapi
+
+Serve [VAPI's Custom Knowledge Base webhook](https://docs.vapi.ai/knowledge-base/custom-knowledge-base)
+from MemoAir voice memory. Phase 1 retrieves from the shared org index.
+
+## Install
+
+```bash
+pip install memoair-vapi
+```
+
+## Quick start
+
+```python
+import json
+
+from memoair_vapi import MemoAirVapiSearch, verify_vapi_signature
+
+search = MemoAirVapiSearch(
+    api_key="memoair_pk_...",
+    project_id="proj_xxx",
+    agent_id="agent_xxx",
+    top_k=5,
+)
+
+# In your webhook handler (raw_body = exact request bytes):
+if not verify_vapi_signature(raw_body, signature_header, secret):
+    ...  # return 401
+
+payload = json.loads(raw_body)
+documents = await search.handle_request(payload)  # -> {"documents": [...]}
+```
+
+`handle_request` dispatches on `message.type`: `knowledge-base-request` returns
+documents; any other type is acked with `{}`. A malformed knowledge-base request
+raises `VapiWebhookError` (map it to HTTP 400). Retrieval failures degrade to
+`{"documents": []}` so a live call never breaks.
+
+A runnable FastAPI server is in [`examples/vapi/`](../../examples/vapi/).
+
+## Docs
+
+https://docs.memoair.dev/voice/integrations/vapi

memoair_vapi-0.1.0/memoair_vapi/__init__.py

@@ -0,0 +1,25 @@
+from memoair_vapi._search import MemoAirVapiSearch
+from memoair_vapi._signature import verify_vapi_signature
+from memoair_vapi._types import (
+    VapiDocument,
+    VapiKnowledgeBaseResponse,
+    VapiWebhookError,
+)
+from memoair_vapi._webhook import (
+    KNOWLEDGE_BASE_REQUEST,
+    documents_from_search_result,
+    extract_query,
+    message_type,
+)
+
+__all__ = [
+    "MemoAirVapiSearch",
+    "verify_vapi_signature",
+    "VapiDocument",
+    "VapiKnowledgeBaseResponse",
+    "VapiWebhookError",
+    "KNOWLEDGE_BASE_REQUEST",
+    "documents_from_search_result",
+    "extract_query",
+    "message_type",
+]

memoair_vapi-0.1.0/memoair_vapi/_search.py

@@ -0,0 +1,114 @@
+"""MemoAirVapiSearch — serve VAPI Custom Knowledge Base from MemoAir org memory."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from memoair_voice import MemoAirVoiceClient
+
+from memoair_vapi._types import VapiKnowledgeBaseResponse, VapiWebhookError
+from memoair_vapi._webhook import (
+    KNOWLEDGE_BASE_REQUEST,
+    documents_from_search_result,
+    extract_query,
+    message_type,
+)
+
+_logger = logging.getLogger("memoair_vapi")
+
+DEFAULT_TOP_K = 5
+DEFAULT_SEARCH_TIMEOUT_MS = 250
+DEFAULT_CLOUD_BASE_URL = "https://backend.memoair.space"
+
+
+class MemoAirVapiSearch:
+    """Wraps a MemoAirVoiceClient to answer VAPI knowledge-base-request webhooks.
+
+    Phase 1 is org-lane-only. ``user_id`` / ``lanes`` are accepted now as inert
+    seams: when ``org_only`` is True they are ignored and the org lane is forced.
+    Phase 2 will route a supplied ``user_id`` to per-user lanes.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        project_id: str,
+        agent_id: str,
+        top_k: int = DEFAULT_TOP_K,
+        org_only: bool = True,
+        cloud_base_url: str = DEFAULT_CLOUD_BASE_URL,
+        search_timeout_ms: int = DEFAULT_SEARCH_TIMEOUT_MS,
+        max_concurrent_users: int = 4,
+        client: Any | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not project_id:
+            raise ValueError("project_id is required")
+        if not agent_id:
+            raise ValueError("agent_id is required")
+
+        self._project_id = project_id
+        self._org_only = org_only
+        self._top_k = int(top_k)
+        self._search_timeout_ms = int(search_timeout_ms)
+        self._client = client or MemoAirVoiceClient(
+            api_key=api_key,
+            project_id=project_id,
+            agent_id=agent_id,
+            cloud_base_url=cloud_base_url,
+            org_only=org_only,
+            max_concurrent_users=max_concurrent_users,
+        )
+
+    async def search(
+        self,
+        query: str,
+        *,
+        user_id: str | None = None,
+        lanes: list[str] | None = None,
+    ) -> VapiKnowledgeBaseResponse:
+        effective_lanes = ["org"] if self._org_only else (lanes or ["org"])
+        result = await self._client.search_memory(
+            query,
+            lanes=effective_lanes,
+            timeout_ms=self._search_timeout_ms,
+        )
+        docs = documents_from_search_result(result, top_k=self._top_k)
+        return VapiKnowledgeBaseResponse(documents=docs)
+
+    async def handle_request(
+        self,
+        payload: Mapping[str, Any],
+        *,
+        user_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Parse a VAPI webhook payload, dispatch on type, return a JSON-able dict.
+
+        Non-``knowledge-base-request`` types are acked with ``{}``. Malformed
+        KB payloads raise VapiWebhookError (server maps to 400). Search failures
+        degrade to ``{"documents": []}`` so the live call keeps flowing.
+
+        A non-object payload (valid JSON array/scalar reaching a public
+        endpoint) is treated as malformed rather than allowed to raise an
+        uncaught AttributeError — preserves the never-500 contract.
+        """
+        if not isinstance(payload, Mapping):
+            raise VapiWebhookError("payload is not a JSON object")
+        if message_type(payload) != KNOWLEDGE_BASE_REQUEST:
+            return {}
+        query = extract_query(payload)
+        try:
+            response = await self.search(query, user_id=user_id)
+        except Exception as exc:  # noqa: BLE001 — degrade, never 500 mid-call
+            _logger.warning(
+                "vapi search failed (project=%s): %s", self._project_id, exc
+            )
+            return {"documents": []}
+        return response.to_dict()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

memoair_vapi-0.1.0/memoair_vapi/_signature.py

@@ -0,0 +1,27 @@
+"""HMAC-SHA256 verification for VAPI webhook requests."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_vapi_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
+    """Return True iff ``signature_header`` is a valid HMAC-SHA256 of
+    ``raw_body`` under ``secret``.
+
+    VAPI's docs are inconsistent about whether the header carries a bare hex
+    digest or a ``sha256=<hex>`` form, so both are accepted. Comparison is
+    timing-safe. Any missing input (empty body, header, or secret) returns
+    False rather than raising.
+    """
+    if not raw_body or not signature_header or not secret:
+        return False
+    candidate = signature_header.strip()
+    if candidate.lower().startswith("sha256="):
+        candidate = candidate[len("sha256="):]
+    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
+    try:
+        return hmac.compare_digest(candidate, expected)
+    except (TypeError, ValueError):
+        return False

memoair_vapi-0.1.0/memoair_vapi/_types.py

@@ -0,0 +1,38 @@
+"""Public types for the memoair-vapi package."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class VapiWebhookError(Exception):
+    """Raised when a VAPI webhook payload is malformed (missing message,
+    missing/empty messages, or no user turn with content)."""
+
+
+@dataclass(frozen=True)
+class VapiDocument:
+    """A single document returned to VAPI's Custom Knowledge Base webhook."""
+
+    content: str
+    similarity: float | None = None
+    uuid: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"content": self.content}
+        if self.similarity is not None:
+            out["similarity"] = self.similarity
+        if self.uuid is not None:
+            out["uuid"] = self.uuid
+        return out
+
+
+@dataclass(frozen=True)
+class VapiKnowledgeBaseResponse:
+    """The `{"documents": [...]}` response body VAPI expects."""
+
+    documents: list[VapiDocument] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"documents": [d.to_dict() for d in self.documents]}

memoair_vapi-0.1.0/memoair_vapi/_webhook.py

@@ -0,0 +1,81 @@
+"""Parse VAPI Custom Knowledge Base requests and map MemoAir results to docs."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from memoair_voice import SearchResult
+
+from memoair_vapi._types import VapiDocument, VapiWebhookError
+
+KNOWLEDGE_BASE_REQUEST = "knowledge-base-request"
+
+
+def message_type(payload: Mapping[str, Any]) -> str | None:
+    """Return ``message.type`` from a VAPI webhook payload, or None."""
+    message = payload.get("message")
+    if isinstance(message, Mapping):
+        mtype = message.get("type")
+        if isinstance(mtype, str):
+            return mtype
+    return None
+
+
+def extract_query(payload: Mapping[str, Any]) -> str:
+    """Return the latest user message content from a knowledge-base-request.
+
+    Raises VapiWebhookError if the payload is malformed or has no user turn.
+    """
+    message = payload.get("message")
+    if not isinstance(message, Mapping):
+        raise VapiWebhookError("payload missing 'message' object")
+    messages = message.get("messages")
+    if not isinstance(messages, list) or not messages:
+        raise VapiWebhookError("payload 'message.messages' missing or empty")
+    for item in reversed(messages):
+        if isinstance(item, Mapping) and item.get("role") == "user":
+            content = item.get("content")
+            if isinstance(content, str) and content.strip():
+                return content
+    raise VapiWebhookError("no user message with content found")
+
+
+def documents_from_search_result(result: SearchResult, *, top_k: int) -> list[VapiDocument]:
+    """Map a SearchResult's org lane to VAPI documents.
+
+    Org items follow the runtime contract {docId, chunkId, text, score} but we
+    read defensively across alternative keys. Falls back to a single document
+    carrying contextText when the org lane is empty.
+    """
+    docs: list[VapiDocument] = []
+    for item in result.org or []:
+        if not isinstance(item, Mapping):
+            continue
+        content = item.get("text") or item.get("content") or item.get("chunk")
+        if not isinstance(content, str) or not content.strip():
+            continue
+        raw_score = item.get("score")
+        if raw_score is None:
+            raw_score = item.get("similarity")
+        similarity = float(raw_score) if isinstance(raw_score, (int, float)) else None
+        raw_uuid = (
+            item.get("chunkId")
+            or item.get("docId")
+            or item.get("id")
+            or item.get("uuid")
+        )
+        docs.append(
+            VapiDocument(
+                content=content,
+                similarity=similarity,
+                uuid=str(raw_uuid) if raw_uuid is not None else None,
+            )
+        )
+
+    if not docs and result.contextText and result.contextText.strip():
+        docs.append(VapiDocument(content=result.contextText))
+
+    if top_k and top_k > 0:
+        return docs[:top_k]
+    return docs

memoair_vapi-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memoair-vapi"
+version = "0.1.0"
+description = "VAPI Custom Knowledge Base integration for MemoAir voice memory"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "MemoAir", email = "hello@memoair.dev" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+keywords = ["ai", "agents", "vapi", "memory", "memoair", "voice", "voice-agents"]
+dependencies = [
+    "memoair-voice>=0.3.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+]
+
+[project.urls]
+Homepage = "https://memoair.dev"
+Documentation = "https://docs.memoair.dev/voice/integrations/vapi"
+Repository = "https://github.com/memoair/memoair-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["memoair_vapi"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501", "B008"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["memoair_vapi"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

memoair_vapi-0.1.0/tests/test_search.py

@@ -0,0 +1,102 @@
+import logging
+
+import pytest
+from memoair_voice import MemoAirVoiceMemoryError, SearchResult
+
+from memoair_vapi._search import MemoAirVapiSearch
+from memoair_vapi._types import VapiWebhookError
+from memoair_vapi._webhook import KNOWLEDGE_BASE_REQUEST
+
+
+class FakeVoiceClient:
+    """In-memory stand-in for MemoAirVoiceClient (org_only)."""
+
+    def __init__(self, result: "SearchResult | None" = None, raises: "Exception | None" = None) -> None:
+        self._result = result
+        self._raises = raises
+        self.closed = False
+        self.calls: list = []
+
+    async def search_memory(self, query, *, lanes=None, timeout_ms=None, **kwargs):
+        self.calls.append({"query": query, "lanes": lanes, "timeout_ms": timeout_ms})
+        if self._raises is not None:
+            raise self._raises
+        return self._result
+
+    async def aclose(self) -> None:
+        self.closed = True
+
+
+def _result(org: list, context_text: str = "") -> SearchResult:
+    return SearchResult(
+        contextText=context_text, profile=None, working=[],
+        permanent=[], org=org, sources=[], trace={},
+    )
+
+
+def _kb_payload(messages: list) -> dict:
+    return {"message": {"type": KNOWLEDGE_BASE_REQUEST, "messages": messages}}
+
+
+def _search(client: "FakeVoiceClient", **overrides) -> MemoAirVapiSearch:
+    kwargs = {"api_key": "memoair_pk_t", "project_id": "proj_t", "agent_id": "agent_t", "client": client}
+    kwargs.update(overrides)
+    return MemoAirVapiSearch(**kwargs)
+
+
+def test_constructor_requires_api_key() -> None:
+    with pytest.raises(ValueError, match="api_key"):
+        MemoAirVapiSearch(api_key="", project_id="p", agent_id="a")
+
+
+async def test_search_queries_org_lane() -> None:
+    client = FakeVoiceClient(_result([
+        {"chunkId": "c1", "text": "hello", "score": 0.9},
+    ]))
+    search = _search(client, search_timeout_ms=300)
+    resp = await search.search("hi there")
+    assert client.calls == [{"query": "hi there", "lanes": ["org"], "timeout_ms": 300}]
+    assert resp.to_dict() == {"documents": [{"content": "hello", "similarity": 0.9, "uuid": "c1"}]}
+
+
+async def test_handle_request_happy_path() -> None:
+    client = FakeVoiceClient(_result([{"chunkId": "c1", "text": "answer", "score": 0.8}]))
+    search = _search(client)
+    out = await search.handle_request(_kb_payload([{"role": "user", "content": "q?"}]))
+    assert out == {"documents": [{"content": "answer", "similarity": 0.8, "uuid": "c1"}]}
+
+
+async def test_handle_request_non_kb_type_acks() -> None:
+    client = FakeVoiceClient(_result([]))
+    search = _search(client)
+    out = await search.handle_request({"message": {"type": "end-of-call-report"}})
+    assert out == {}
+    assert client.calls == []
+
+
+async def test_handle_request_malformed_raises() -> None:
+    search = _search(FakeVoiceClient(_result([])))
+    with pytest.raises(VapiWebhookError):
+        await search.handle_request(_kb_payload([{"role": "assistant", "content": "x"}]))
+
+
+async def test_handle_request_non_object_payload_raises() -> None:
+    search = _search(FakeVoiceClient(_result([])))
+    with pytest.raises(VapiWebhookError):
+        await search.handle_request([])  # type: ignore[arg-type]
+
+
+async def test_handle_request_search_failure_degrades(caplog: pytest.LogCaptureFixture) -> None:
+    client = FakeVoiceClient(raises=MemoAirVoiceMemoryError(code="runtime.timeout", message="boom"))
+    search = _search(client)
+    with caplog.at_level(logging.WARNING, logger="memoair_vapi"):
+        out = await search.handle_request(_kb_payload([{"role": "user", "content": "q?"}]))
+    assert out == {"documents": []}
+    assert "vapi search failed" in caplog.text
+
+
+async def test_aclose_closes_client() -> None:
+    client = FakeVoiceClient(_result([]))
+    search = _search(client)
+    await search.aclose()
+    assert client.closed is True

memoair_vapi-0.1.0/tests/test_signature.py

@@ -0,0 +1,33 @@
+import hashlib
+import hmac
+
+from memoair_vapi._signature import verify_vapi_signature
+
+SECRET = "shh-secret"
+BODY = b'{"message":{"type":"knowledge-base-request"}}'
+
+
+def _sig(body: bytes, secret: str) -> str:
+    return hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+
+
+def test_valid_raw_hex_signature() -> None:
+    assert verify_vapi_signature(BODY, _sig(BODY, SECRET), SECRET) is True
+
+
+def test_valid_sha256_prefixed_signature() -> None:
+    assert verify_vapi_signature(BODY, f"sha256={_sig(BODY, SECRET)}", SECRET) is True
+
+
+def test_invalid_signature() -> None:
+    assert verify_vapi_signature(BODY, _sig(BODY, "wrong"), SECRET) is False
+
+
+def test_tampered_body() -> None:
+    assert verify_vapi_signature(b"tampered", _sig(BODY, SECRET), SECRET) is False
+
+
+def test_missing_secret_or_header() -> None:
+    assert verify_vapi_signature(BODY, _sig(BODY, SECRET), "") is False
+    assert verify_vapi_signature(BODY, "", SECRET) is False
+    assert verify_vapi_signature(b"", _sig(BODY, SECRET), SECRET) is False

memoair_vapi-0.1.0/tests/test_webhook.py

@@ -0,0 +1,95 @@
+import pytest
+from memoair_voice import SearchResult
+
+from memoair_vapi._types import VapiWebhookError
+from memoair_vapi._webhook import (
+    KNOWLEDGE_BASE_REQUEST,
+    documents_from_search_result,
+    extract_query,
+    message_type,
+)
+
+
+def _kb_payload(messages: list) -> dict:
+    return {"message": {"type": KNOWLEDGE_BASE_REQUEST, "messages": messages}}
+
+
+def test_extract_query_returns_latest_user_message() -> None:
+    payload = _kb_payload([
+        {"role": "user", "content": "first"},
+        {"role": "assistant", "content": "ok"},
+        {"role": "user", "content": "latest question"},
+    ])
+    assert extract_query(payload) == "latest question"
+
+
+def test_extract_query_missing_message_raises() -> None:
+    with pytest.raises(VapiWebhookError):
+        extract_query({})
+
+
+def test_extract_query_empty_messages_raises() -> None:
+    with pytest.raises(VapiWebhookError):
+        extract_query({"message": {"type": KNOWLEDGE_BASE_REQUEST, "messages": []}})
+
+
+def test_extract_query_no_user_turn_raises() -> None:
+    with pytest.raises(VapiWebhookError):
+        extract_query(_kb_payload([{"role": "assistant", "content": "hi"}]))
+
+
+def test_message_type() -> None:
+    assert message_type(_kb_payload([])) == KNOWLEDGE_BASE_REQUEST
+    assert message_type({"message": {"type": "end-of-call-report"}}) == "end-of-call-report"
+    assert message_type({}) is None
+
+
+def _result(org: list, context_text: str = "") -> SearchResult:
+    return SearchResult(
+        contextText=context_text, profile=None, working=[],
+        permanent=[], org=org, sources=[], trace={},
+    )
+
+
+def test_documents_from_org_items() -> None:
+    result = _result([
+        {"docId": "doc_42", "chunkId": "doc_42:7", "text": "Standup is 10:30 IST.", "score": 0.71},
+        {"docId": "doc_9", "chunkId": "doc_9:1", "text": "Returns within 30 days.", "score": 0.6},
+    ])
+    docs = documents_from_search_result(result, top_k=5)
+    assert [d.to_dict() for d in docs] == [
+        {"content": "Standup is 10:30 IST.", "similarity": 0.71, "uuid": "doc_42:7"},
+        {"content": "Returns within 30 days.", "similarity": 0.6, "uuid": "doc_9:1"},
+    ]
+
+
+def test_documents_top_k_truncates() -> None:
+    result = _result([
+        {"chunkId": f"c{i}", "text": f"t{i}", "score": 0.5} for i in range(10)
+    ])
+    assert len(documents_from_search_result(result, top_k=3)) == 3
+
+
+def test_documents_fallback_to_context_text() -> None:
+    result = _result([], context_text="some recalled context")
+    docs = documents_from_search_result(result, top_k=5)
+    assert [d.to_dict() for d in docs] == [{"content": "some recalled context"}]
+
+
+def test_documents_empty_when_no_org_and_no_context() -> None:
+    assert documents_from_search_result(_result([]), top_k=5) == []
+
+
+def test_documents_defensive_keys_and_zero_score() -> None:
+    result = _result([
+        {"docId": "d1", "text": "zero score kept", "score": 0.0},
+        {"content": "alt content key", "similarity": 0.4, "docId": "d2"},
+        "not-a-mapping",
+        {"chunk": "alt chunk key", "id": "d3"},
+    ])
+    docs = documents_from_search_result(result, top_k=10)
+    assert [d.to_dict() for d in docs] == [
+        {"content": "zero score kept", "similarity": 0.0, "uuid": "d1"},
+        {"content": "alt content key", "similarity": 0.4, "uuid": "d2"},
+        {"content": "alt chunk key", "uuid": "d3"},
+    ]