openvox-core 0.1.0__tar.gz

openvox_core-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+.next/
+out/
+dist/
+.turbo/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+
+# Env
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# Editor
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Local data (local-first)
+data/
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Docker volumes (when bind-mounted)
+.docker-data/
+
+# OpenVox local state directory
+.openvox/

openvox_core-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: openvox-core
+Version: 0.1.0
+Summary: Local-first, open-source voice agent platform — install with pip, run as a daemon, no Docker required.
+Project-URL: Homepage, https://github.com/amznsri/openvox
+Project-URL: Documentation, https://github.com/amznsri/openvox/tree/main/docs
+Project-URL: Repository, https://github.com/amznsri/openvox
+Project-URL: Issues, https://github.com/amznsri/openvox/issues
+Project-URL: Changelog, https://github.com/amznsri/openvox/blob/main/docs/SESSION_LOG.md
+Author: OpenVox Contributors
+License: Apache-2.0
+Keywords: agent,ai,rtc,stt,telegram,tts,twilio,voice,whatsapp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: apscheduler>=3.10.4
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: authlib>=1.3.0
+Requires-Dist: boto3>=1.35.0
+Requires-Dist: certifi>=2024.8.30
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: google-cloud-storage>=2.18.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: oss2>=2.18.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: pydantic-settings>=2.5.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pydub>=0.25.1
+Requires-Dist: pypdf>=4.3.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: python-multipart>=0.0.12
+Requires-Dist: redis[hiredis]>=5.1.0
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: silero-vad>=5.1.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.35
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: tos>=2.7.0
+Requires-Dist: twilio>=9.3.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: watchfiles>=0.24.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: local-stt
+Requires-Dist: openai-whisper>=20240930; extra == 'local-stt'
+Provides-Extra: postgres
+Provides-Extra: whatsapp
+Description-Content-Type: text/markdown
+
+# openvox-core
+
+The OpenVox voice pipeline. FastAPI + asyncio orchestrator that ties STT,
+LLM, TTS, RTC, telephony, and pluggable skills together.
+
+See the top-level [README](../../README.md).

openvox_core-0.1.0/README.md

@@ -0,0 +1,6 @@
+# openvox-core
+
+The OpenVox voice pipeline. FastAPI + asyncio orchestrator that ties STT,
+LLM, TTS, RTC, telephony, and pluggable skills together.
+
+See the top-level [README](../../README.md).

openvox_core-0.1.0/openvox/__init__.py

@@ -0,0 +1,3 @@
+"""OpenVox — local-first voice agent platform."""
+
+__version__ = "0.1.0"

openvox_core-0.1.0/openvox/api/__init__.py

@@ -0,0 +1,3 @@
+from openvox.api.app import create_app
+
+__all__ = ["create_app"]

openvox_core-0.1.0/openvox/api/app.py

@@ -0,0 +1,210 @@
+"""FastAPI app factory."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from openvox.api.routes import (
+    admin as admin_routes,
+    agents,
+    auth as auth_routes,
+    documents as documents_routes,
+    evals as evals_routes,
+    health,
+    jobs as jobs_routes,
+    mcp as mcp_routes,
+    playground,
+    pricing as pricing_routes,
+    providers as providers_routes,
+    rtc,
+    sessions,
+    skills as skills_routes,
+    storage as storage_routes,
+    telephony,
+    templates as templates_routes,
+)
+from openvox.api.ws import twilio_stream as twilio_ws
+from openvox.api.ws import voice as voice_ws
+from openvox.config import get_settings
+from openvox.db import init_db
+from openvox.providers.bootstrap import register_builtins
+from openvox.scheduler import start_scheduler, stop_scheduler
+from openvox.skills.registry import get_skill_registry
+from openvox.skills.watcher import start_watcher, stop_watcher
+
+logger = logging.getLogger(__name__)
+
+
+async def _seed_builtin_personas() -> None:
+    """Upsert the built-in synthetic personas on startup.
+
+    We upsert by id so edits to the prompt in eval/personas.py take
+    effect without manual intervention, but user-edited personas
+    (different id) are left alone.
+    """
+    from openvox.db import db_session
+    from openvox.db.models import Persona
+    from openvox.eval.personas import BUILTIN_PERSONAS
+
+    async with db_session() as s:
+        for entry in BUILTIN_PERSONAS:
+            existing = await s.get(Persona, entry["id"])
+            if existing is None:
+                p = Persona(
+                    id=entry["id"],
+                    name=entry["name"],
+                    description=entry.get("description", ""),
+                    system_prompt=entry["system_prompt"],
+                    tags=entry.get("tags", []),
+                    builtin=True,
+                )
+                s.add(p)
+            else:
+                # Refresh prompt + tags on every boot so prompt iterations stick.
+                existing.name = entry["name"]
+                existing.description = entry.get("description", "")
+                existing.system_prompt = entry["system_prompt"]
+                existing.tags = entry.get("tags", [])
+                existing.builtin = True
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    settings = get_settings()
+    settings.data_dir.mkdir(parents=True, exist_ok=True)
+    register_builtins()
+    get_skill_registry()  # discover
+    await init_db()
+    await _seed_builtin_personas()
+    await start_scheduler()
+    await start_watcher()  # hot-reload skills dropped in ~/.openvox/skills/
+    # Phase 2: start telegram polling tasks for any agent connected
+    # in polling mode. Webhook-mode agents bootstrap themselves on the
+    # next incoming Telegram POST — no startup action needed.
+    from openvox.telephony.telegram_polling import start_all_pollers, stop_all_pollers
+    await start_all_pollers()
+    # WhatsApp Personal: reconnect bridge sessions for any agent whose
+    # channels.whatsapp_personal.enabled == true. No-op if the bridge
+    # container isn't running (opt-in via --profile whatsapp).
+    from openvox.telephony.whatsapp_personal import (
+        start_all_sessions as wpp_start_all,
+        stop_all_sessions as wpp_stop_all,
+    )
+    await wpp_start_all()
+    logger.info("OpenVox core started — auth=%s storage=%s", settings.openvox_auth, settings.storage_backend)
+    yield
+    await wpp_stop_all()
+    await stop_all_pollers()
+    await stop_watcher()
+    await stop_scheduler()
+    logger.info("OpenVox core shutting down")
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    logging.basicConfig(level=settings.log_level.upper())
+
+    app = FastAPI(
+        title="OpenVox Core",
+        description="Voice agent pipeline (STT + LLM + TTS + RTC + telephony).",
+        version="0.1.0",
+        lifespan=_lifespan,
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # local-first — accept dashboard from any local origin
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(health.router)
+    app.include_router(auth_routes.router, prefix="/api/v1/auth", tags=["auth"])
+    app.include_router(admin_routes.router, prefix="/api/v1/admin", tags=["admin"])
+    app.include_router(agents.router, prefix="/api/v1/agents", tags=["agents"])
+    app.include_router(documents_routes.router, prefix="/api/v1/agents", tags=["documents"])
+    app.include_router(sessions.router, prefix="/api/v1/sessions", tags=["sessions"])
+    app.include_router(providers_routes.router, prefix="/api/v1/providers", tags=["providers"])
+    app.include_router(skills_routes.router, prefix="/api/v1/skills", tags=["skills"])
+    app.include_router(templates_routes.router, prefix="/api/v1/templates", tags=["templates"])
+    app.include_router(rtc.router, prefix="/api/v1/rtc", tags=["rtc"])
+    app.include_router(jobs_routes.router, prefix="/api/v1/jobs", tags=["jobs"])
+    app.include_router(mcp_routes.router, prefix="/api/v1/mcp", tags=["mcp"])
+    app.include_router(telephony.router, prefix="/api/v1/telephony", tags=["telephony"])
+    app.include_router(pricing_routes.router, prefix="/api/v1/pricing", tags=["pricing"])
+    app.include_router(evals_routes.router, prefix="/api/v1/evals", tags=["evals"])
+    app.include_router(playground.router, prefix="/api/v1/playground", tags=["playground"])
+    app.include_router(storage_routes.router, prefix="/storage", tags=["storage"])
+    app.include_router(voice_ws.router)
+    app.include_router(twilio_ws.router)
+
+    # ── Optional static-dashboard serving ───────────────────────────
+    # Phase 1 PR-3 scaffolding: when the dashboard has been built with
+    # BUILD_OUTPUT=export (Next.js static export → `out/` directory),
+    # FastAPI serves it at /dashboard/* on the same port as the API.
+    # This is what enables the single-process CLI experience
+    # (`openvox run` → one process, browser opens to localhost:8000/dashboard).
+    #
+    # Discovery order — first existing path wins:
+    #   1. OPENVOX_DASHBOARD_PATH env var (explicit override)
+    #   2. /app/dashboard_static/    (Docker/CLI install — bundled at build)
+    #   3. ../apps/dashboard/out/    (repo-relative dev workflow)
+    #
+    # If none of the above exist, the mount is silently skipped —
+    # browsers hitting /dashboard get 404, which is correct for Docker
+    # mode (where the separate `openvox-dashboard` container handles it).
+    #
+    # Today this is no-op: the dashboard's static-export build pipeline
+    # ships in a follow-up commit (the agents/[id] route needs to be
+    # refactored to query params first — Next.js static export can't
+    # handle dynamic path params for runtime-created IDs). The mount
+    # itself is committed now so we don't have to revisit api/app.py
+    # in that follow-up — just produce the out/ directory and it
+    # gets served automatically.
+    _maybe_mount_dashboard_static(app)
+
+    return app
+
+
+def _maybe_mount_dashboard_static(app: FastAPI) -> None:
+    """Mount the built dashboard static files under /dashboard/* if available.
+
+    See the comment block in create_app() above for the discovery
+    rules + why this is a no-op today. Pulled into its own function so
+    it can be unit-tested + so the mount logic doesn't clutter the
+    main app factory.
+    """
+    import os
+    from pathlib import Path
+
+    from fastapi.staticfiles import StaticFiles
+
+    explicit = os.environ.get("OPENVOX_DASHBOARD_PATH")
+    candidates: list[Path] = []
+    if explicit:
+        candidates.append(Path(explicit))
+    candidates.append(Path("/app/dashboard_static"))
+    # Repo-relative — works in `openvox run` invoked from the repo root.
+    candidates.append(Path(__file__).resolve().parent.parent.parent.parent.parent
+                      / "apps" / "dashboard" / "out")
+
+    for path in candidates:
+        if path.is_dir() and (path / "index.html").exists():
+            app.mount(
+                "/dashboard",
+                StaticFiles(directory=str(path), html=True),
+                name="dashboard",
+            )
+            logger.info("dashboard static files mounted at /dashboard from %s", path)
+            return
+
+    # Not found — that's fine in Docker mode where the separate
+    # `openvox-dashboard` container serves the dashboard on its own port.
+    logger.debug(
+        "no dashboard static files found — /dashboard will 404. "
+        "Either set OPENVOX_DASHBOARD_PATH or use Docker dashboard service."
+    )

openvox_core-0.1.0/openvox/api/routes/admin.py

@@ -0,0 +1,133 @@
+"""Admin endpoints — backing API for the dashboard's first-run wizard.
+
+Phase 3 of `docs/PLANNING_SESSION15.md`. Three endpoints:
+
+- ``GET  /api/v1/admin/setup/status``   — what's configured + is setup complete?
+- ``POST /api/v1/admin/setup/keys``     — save provider keys (encrypted-at-rest)
+- ``DELETE /api/v1/admin/setup/keys``   — remove a stored key
+
+The dashboard's wizard pages (``apps/dashboard/src/app/dashboard/setup/*``)
+poll status on mount, present the form when ``complete == false``, and
+POST the user's pasted keys here. The encrypted-store layer
+(``openvox/secrets.py``) handles persistence; this module is just the
+HTTP shell.
+
+Security notes
+==============
+- Endpoints don't require auth today because OpenVox runs local-first;
+  the operator and the admin are the same person. When
+  ``OPENVOX_AUTH=enabled`` (multi-tenant cloud), these must be gated
+  behind admin-only authorization — see the TODO at the top of
+  ``check_admin()`` below.
+- POSTed values flow into Fernet-encrypted storage. Never logged or
+  returned in any response.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from openvox import secrets as secret_store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def check_admin() -> None:
+    """Authorization placeholder for the multi-tenant future.
+
+    Today: no-op. OpenVox runs local-first; operator == admin.
+
+    When ``OPENVOX_AUTH=enabled`` ships (cloud mode), this should
+    inspect the request's bearer token and 403 if the caller isn't
+    an admin. Keep all admin endpoints calling this so the eventual
+    gate has a single edit point.
+    """
+    # TODO: when OPENVOX_AUTH lands, verify admin role from JWT.
+    return None
+
+
+class SetupKeysRequest(BaseModel):
+    """Save one or more provider keys at once.
+
+    Example body:
+        {
+          "provider": "byteplus",
+          "keys": {
+            "llm_api_key": "01a2b3c4...",
+            "voice_api_key": "01a2b3c4..."
+          }
+        }
+
+    An empty string for a key value deletes the stored key (caller
+    can use this to "forget" a key without a separate DELETE call).
+    """
+
+    provider: str = Field(..., min_length=1, max_length=64)
+    keys: dict[str, str] = Field(default_factory=dict)
+
+
+@router.get("/setup/status")
+async def setup_status() -> dict[str, Any]:
+    """Tell the dashboard whether the first-run wizard should run.
+
+    Used by ``apps/dashboard/src/app/dashboard/layout.tsx`` (or
+    equivalent) on mount: if ``complete == false`` and the user
+    isn't already on /dashboard/setup, redirect them there.
+    """
+    check_admin()
+    return await secret_store.setup_complete()
+
+
+@router.post("/setup/keys")
+async def setup_keys(req: SetupKeysRequest) -> dict[str, Any]:
+    """Persist a batch of provider keys.
+
+    Returns the updated setup-status so the wizard can refresh its
+    "what's configured" panel without a second round-trip.
+    """
+    check_admin()
+
+    provider = req.provider.strip().lower()
+    if not provider:
+        raise HTTPException(400, "provider is required")
+    if not req.keys:
+        raise HTTPException(400, "keys map must be non-empty")
+
+    saved: list[str] = []
+    deleted: list[str] = []
+    for key_name, value in req.keys.items():
+        try:
+            await secret_store.set_provider_key(provider, key_name, value)
+        except ValueError as e:
+            raise HTTPException(400, f"invalid key '{key_name}': {e}") from e
+        (deleted if value == "" else saved).append(key_name)
+
+    logger.info(
+        "admin/setup/keys: provider=%s saved=%s deleted=%s",
+        provider, saved, deleted,
+    )
+
+    return {
+        "ok": True,
+        "saved": saved,
+        "deleted": deleted,
+        "status": await secret_store.setup_complete(),
+    }
+
+
+class DeleteKeyRequest(BaseModel):
+    provider: str = Field(..., min_length=1, max_length=64)
+    key_name: str = Field(..., min_length=1, max_length=64)
+
+
+@router.delete("/setup/keys")
+async def delete_key(req: DeleteKeyRequest) -> dict[str, Any]:
+    """Remove a single stored key — env-var fallback resumes."""
+    check_admin()
+    await secret_store.delete_provider_key(req.provider, req.key_name)
+    return {"ok": True, "status": await secret_store.setup_complete()}