Cogniverse Setup & Installation Guide¶

Prerequisites¶

System Requirements¶

• Python: 3.12
• Storage: 20GB+ disk space
• GPU: optional but recommended for video processing. Supported:
• NVIDIA CUDA (Linux/x86_64) — torch+cu128 wheels
• AMD ROCm (Linux/x86_64) — torch+rocm6.4 wheels (Strix Halo / gfx1151, MI300, RX 7000 series)
• Apple Silicon MPS (macOS arm64) — default PyPI torch ships MPS support
• CPU-only fallback on Linux
• OS: Linux/x86_64 or macOS arm64. Windows is not a supported resolution target (the workspace's [tool.uv] environments excludes win32).

Required Software¶

• Docker, kubectl, helm, k3d: cogniverse up checks for them and offers to install missing ones
• Git: For repository management
• uv: Python package manager (required for workspace support)
• rocminfo (AMD ROCm hosts only): used by both scripts/install_with_gpu.sh and the CLI's detect_torch_backend() (libs/cli/cogniverse_cli/images.py) to confirm ROCm before picking torch+rocm wheels. The amdgpu kernel module alone isn't enough — without rocminfo the detectors fall back to CPU. Install via sudo apt-get install -y rocminfo (Debian/ Ubuntu) or the AMD ROCm meta-package, or override with COGNIVERSE_TORCH_BACKEND=rocm.
• nvidia-smi (NVIDIA hosts only): needed for CUDA auto-detection. Comes with the NVIDIA driver — no separate install. Override with COGNIVERSE_TORCH_BACKEND=cuda if you want to force CUDA wheels without the smi tool reachable.

Quick Start Installation¶

1. Clone Repository¶

git clone https://github.com/amit-jain/cogniverse.git
cd cogniverse

2. Install Python Dependencies¶

# Install uv (use the standalone installer; `pip install uv` is blocked
# on Ubuntu 24.04+ / Debian 12+ / Fedora 38+ by PEP 668)
curl -LsSf https://astral.sh/uv/0.12.19/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Sync all workspace packages with the right PyTorch backend for this host.
# Autodetects macOS / NVIDIA / AMD ROCm / CPU and picks the matching wheels.
scripts/install_with_gpu.sh

The wrapper exists because uv sync alone installs the default PyPI torch wheel, which on Linux/x86_64 is the CUDA build (torch==2.8.0+cu128) — wrong on AMD or CPU-only hosts and ~700 MB of useless NVIDIA libraries on machines without an NVIDIA GPU. See "PyTorch backend selection" below for the full story.

Workspace contents (installed in editable mode, all 12 packages — cogniverse-cli comes from the dev dependency group, which uv sync installs by default alongside the rest):

• Foundation Layer: cogniverse_sdk (libs/sdk/), cogniverse_foundation (libs/foundation/)
• Core Layer: cogniverse_core, cogniverse_evaluation, cogniverse_telemetry_phoenix
• Implementation Layer: cogniverse_agents, cogniverse_vespa, cogniverse_synthetic, cogniverse_finetuning
• Application Layer: cogniverse_runtime, cogniverse_cli, cogniverse_messaging

2a. PyTorch backend selection¶

The same pyproject.toml ships to every host (your Mac, a CUDA workstation, this AMD/ROCm box, CI). uv has no native concept of "different default torch wheel per machine," so we use opt-in extras + per-extra wheel-index sources:

scripts/install_with_gpu.sh autodetects the host (uname -s, nvidia-smi, rocminfo) and forwards the right --extra. Override the detection with COGNIVERSE_TORCH_BACKEND=cpu|cuda|rocm|mac. The [tool.uv] conflicts block in pyproject.toml makes the three extras mutually exclusive so you can't accidentally combine them.

Why not uv's torch-backend = "auto"? uv 0.12.19 only honors the torch-backend setting on uv pip install (the legacy interface), not on uv sync / uv lock. Setting it in [tool.uv] is silently ignored during the project workflow we use. If a future uv release wires torch-backend into uv sync, the extras + sources scaffolding can be deleted in favor of a single torch-backend = "auto" line. Until then, extras are how this works.

Avoiding --extra rocm on every command (Linux + ROCm only). Once scripts/install_with_gpu.sh has installed the rocm wheels, plain uv run python ... will re-sync to the lockfile's base set on every invocation and overwrite them. To stop that, add to your shell rc on this machine:

export UV_NO_SYNC=1

Then uv run and bare python (after source .venv/bin/activate) both keep the rocm wheels. The cost: after a pyproject.toml change you must re-run scripts/install_with_gpu.sh manually instead of uv run doing it for you. Do not set UV_NO_SYNC=1 on your Mac — there's nothing to preserve there since the default sync already installs the right MPS torch.

ROCm-specific: Linux device permissions¶

PyTorch's ROCm wheels need access to /dev/kfd (kernel fusion driver) and /dev/dri/renderD*, which on most Linux distros are owned by the render group (and video for some compositors). Without group membership, all GPU calls return hipErrorNoDevice even though import torch works and torch.version.hip looks right — torch.cuda.is_available() silently returns False and you get CPU fallback at full price.

scripts/install_with_gpu.sh warns if the current user isn't in render or video. Fix:

sudo usermod -aG render,video $USER
# Then log out and back in, or in the current shell:
newgrp render

Why ROCm 6.4 (and not 7.0)?¶

The ROCm wheel index pin in pyproject.toml is rocm6.4. ROCm 6.3 added support for Strix Halo / gfx1151, so 6.4 covers it. Bumping to ROCm 7.0 would require torch>=2.10.0, which forces colpali-engine>=0.3.15, which requires transformers>=5.3.0. But pylate==1.4.0 (latest release) caps transformers<=4.56.2, so the upgrade chain is blocked upstream until pylate ships a transformers v5–compatible release. Revisit when that happens.

3. Start Core Services¶

# Start Vespa (vector database)
docker run -d --name vespa \
  -p 8080:8080 -p 19071:19071 \
  -v vespa-data:/opt/vespa/var \
  vespaengine/vespa:latest

# Start Phoenix (telemetry)
docker run -d --name phoenix \
  -p 6006:6006 -p 4317:4317 \
  -v phoenix-data:/data \
  -e PHOENIX_WORKING_DIR=/data \
  arizephoenix/phoenix:latest

# Start Ollama (local LLM)
docker run -d --name ollama \
  -p 11434:11434 \
  -v ollama-data:/root/.ollama \
  ollama/ollama:latest

3a. (Optional) Whisper ASR via vLLM¶

AudioAnalysisAgent.transcribe_audio can run Whisper in-process or POST to a vLLM-served ASR endpoint (chart key inference.vllm_asr, image vllm/vllm-openai-cpu with the vllm[audio] extra). The remote path is the production default — keeps the agent engine-agnostic and lets the cluster scale ASR independently of the runtime.

Run locally:

docker run -d --name cogniverse-vllm-asr \
  -p 8000:8000 \
  -v cogniverse-hf-cache:/root/.cache/huggingface \
  vllm/vllm-openai-cpu:latest \
  serve openai/whisper-large-v3-turbo --task transcription --max-model-len 448

# Smoke test the OpenAI-compatible health endpoint.
curl -s http://localhost:8000/health

Point the agent at it by setting whisper_endpoint on AudioAnalysisDeps. In a Helm-deployed stack the runtime reads it from system_config.inference_service_urls["vllm_asr"], populated by the chart template charts/cogniverse/templates/all-resources.yaml. inference.vllm_asr.enabled defaults to true in charts/cogniverse/values.yaml because the default video-ingestion profiles hard-require transcription; disable it explicitly only if your deployment never ingests video.

For the ingestion side, profiles pick the endpoint by setting inference_services.transcription: "vllm_asr" at profile level. StrategyFactory injects the service name into AudioTranscriptionStrategy's params; the same profile-level map drives embedding routing via inference_services.embedding. AudioProcessor (ingestion) and AudioAnalysisAgent (runtime) both honor the same INFERENCE_SERVICE_URLS lookup.

4. Pull Required Models¶

# Pull Ollama models
docker exec ollama ollama pull gemma3:4b

5. Verify Installation¶

# Check Vespa
curl http://localhost:8080/ApplicationStatus

# Check Phoenix
curl http://localhost:6006/health

# Check Ollama
curl http://localhost:11434/api/tags

UV Workspace Structure¶

Cogniverse uses a UV workspace with a layered architecture:

cogniverse/
├── libs/                         # UV Workspace Packages (12 total)
│   # FOUNDATION LAYER (Pure Interfaces)
│   ├── sdk/                      # cogniverse_sdk
│   │   ├── pyproject.toml
│   │   └── cogniverse_sdk/
│   │       ├── interfaces/       # Backend, ConfigStore, SchemaLoader interfaces
│   │       └── document.py       # Universal document model
│   ├── foundation/               # cogniverse_foundation
│   │   ├── pyproject.toml
│   │   └── cogniverse_foundation/
│   │       ├── config/           # Configuration base classes
│   │       └── telemetry/        # Telemetry interfaces
│   # CORE LAYER
│   ├── core/                     # cogniverse_core
│   │   ├── pyproject.toml
│   │   └── cogniverse_core/
│   │       ├── agents/           # Base agent classes
│   │       ├── common/           # Shared utilities, A2A client
│   │       ├── registries/       # Component registries
│   │       └── memory/           # Memory management
│   ├── evaluation/               # cogniverse_evaluation
│   │   ├── pyproject.toml
│   │   └── cogniverse_evaluation/
│   │       ├── core/             # Experiment tracker
│   │       ├── metrics/          # Provider-agnostic metrics
│   │       └── data/             # Dataset handling
│   ├── telemetry-phoenix/        # cogniverse_telemetry_phoenix (Plugin)
│   │   ├── pyproject.toml
│   │   └── cogniverse_telemetry_phoenix/
│   │       ├── provider.py       # Phoenix telemetry provider
│   │       └── evaluation/       # Phoenix evaluation provider
│   # IMPLEMENTATION LAYER
│   ├── agents/                   # cogniverse_agents
│   │   ├── pyproject.toml
│   │   └── cogniverse_agents/
│   │       ├── orchestrator_agent.py  # DSPy orchestration & planning
│   │       ├── gateway_agent.py       # GLiNER-based triage
│   │       ├── search_agent.py            # Multi-modal search & reranking
│   │       └── tools/            # Agent tools
│   ├── vespa/                    # cogniverse_vespa
│   │   ├── pyproject.toml
│   │   └── cogniverse_vespa/
│   │       ├── config/           # Config store
│   │       └── json_schema_parser.py  # Schema parser
│   ├── synthetic/                # cogniverse_synthetic
│   │   ├── pyproject.toml
│   │   └── cogniverse_synthetic/
│   │       ├── generators/       # Synthetic data generators
│   │       └── service.py        # Synthetic data service
│   ├── finetuning/               # cogniverse_finetuning
│   │   ├── pyproject.toml
│   │   └── cogniverse_finetuning/
│   │       └── # Fine-tuning capabilities
│   # APPLICATION LAYER
│   ├── runtime/                  # cogniverse_runtime
│   │   ├── pyproject.toml
│   │   └── cogniverse_runtime/
│   │       ├── routers/          # FastAPI routers
│   │       └── ingestion/        # Video processing pipeline
│   ├── cli/                      # cogniverse_cli — the `cogniverse` CLI
│   │   ├── pyproject.toml
│   │   └── cogniverse_cli/
│   │       ├── main.py           # click entry point (`cogniverse up`, `status`, `admin`)
│   │       └── cluster.py        # k3d cluster lifecycle
│   └── messaging/                # cogniverse_messaging
│       ├── pyproject.toml
│       └── cogniverse_messaging/
│           ├── gateway.py        # Messaging gateway (Telegram, etc.)
│           └── runtime_client.py # Client for the runtime's agent API
├── pyproject.toml                # Workspace root
└── uv.lock                       # Unified lockfile

Benefits:

• Layered Architecture: Clear separation between foundation, core, implementation, and application layers

• Independent versioning: Each package can be released separately

• Clear dependencies: Package boundaries enforce clean architecture

• Modular deployment: Install only what you need

• Better IDE support: Clear module boundaries

• Plugin Architecture: Telemetry providers via entry points

Service Architecture¶

flowchart TB
    subgraph Foundation["<span style='color:#000'>Foundation Layer</span>"]
        SDK["<span style='color:#000'>cogniverse_sdk<br/>Interfaces</span>"]
        Foundation_pkg["<span style='color:#000'>cogniverse_foundation<br/>Config Base & Telemetry</span>"]
    end

    subgraph Core["<span style='color:#000'>Core Layer</span>"]
        Core_pkg["<span style='color:#000'>cogniverse_core<br/>Base Classes & Registries</span>"]
        Evaluation["<span style='color:#000'>cogniverse_evaluation<br/>Experiments & Metrics</span>"]
        TelemetryPhoenix["<span style='color:#000'>cogniverse_telemetry_phoenix<br/>Phoenix Provider</span>"]
    end

    subgraph Implementation["<span style='color:#000'>Implementation Layer</span>"]
        Agents["<span style='color:#000'>cogniverse_agents<br/>Routing & Search</span>"]
        Vespa["<span style='color:#000'>cogniverse_vespa<br/>Vespa Backend</span>"]
        Synthetic["<span style='color:#000'>cogniverse_synthetic<br/>Synthetic Data</span>"]
        Finetuning["<span style='color:#000'>cogniverse_finetuning<br/>Model Fine-tuning</span>"]
    end

    subgraph Application["<span style='color:#000'>Application Layer</span>"]
        Runtime["<span style='color:#000'>cogniverse_runtime<br/>FastAPI Server</span>"]
    end

    subgraph Services["<span style='color:#000'>Docker Services</span>"]
        VespaDB["<span style='color:#000'>Vespa:8080<br/>Vector Database</span>"]
        PhoenixSvc["<span style='color:#000'>Phoenix:6006<br/>Telemetry</span>"]
        Ollama["<span style='color:#000'>Ollama:11434<br/>Local LLM</span>"]
    end

    SDK --> Foundation_pkg
    Foundation_pkg --> Core_pkg
    Foundation_pkg --> Evaluation
    Core_pkg --> TelemetryPhoenix
    Evaluation --> TelemetryPhoenix

    Core_pkg --> Agents
    Core_pkg --> Vespa
    Core_pkg --> Synthetic
    Core_pkg --> Finetuning

    Agents --> Runtime
    Vespa --> Runtime
    Synthetic --> Runtime
    Finetuning --> Runtime

    Runtime --> VespaDB
    Runtime --> PhoenixSvc
    Agents --> Ollama

    style Foundation fill:#a5d6a7,stroke:#388e3c,color:#000
    style Core fill:#ce93d8,stroke:#7b1fa2,color:#000
    style Implementation fill:#ffcc80,stroke:#ef6c00,color:#000
    style Application fill:#90caf9,stroke:#1565c0,color:#000
    style Services fill:#b0bec5,stroke:#546e7a,color:#000
    style SDK fill:#a5d6a7,stroke:#388e3c,color:#000
    style Foundation_pkg fill:#a5d6a7,stroke:#388e3c,color:#000
    style Core_pkg fill:#ce93d8,stroke:#7b1fa2,color:#000
    style Evaluation fill:#ce93d8,stroke:#7b1fa2,color:#000
    style TelemetryPhoenix fill:#ce93d8,stroke:#7b1fa2,color:#000
    style Agents fill:#ffcc80,stroke:#ef6c00,color:#000
    style Vespa fill:#ffcc80,stroke:#ef6c00,color:#000
    style Synthetic fill:#ffcc80,stroke:#ef6c00,color:#000
    style Finetuning fill:#ffcc80,stroke:#ef6c00,color:#000
    style Runtime fill:#90caf9,stroke:#1565c0,color:#000
    style VespaDB fill:#b0bec5,stroke:#546e7a,color:#000
    style PhoenixSvc fill:#b0bec5,stroke:#546e7a,color:#000
    style Ollama fill:#b0bec5,stroke:#546e7a,color:#000

Service Ports¶

† 29005 is the k3d/Helm chart nodePort (charts/cogniverse/values.yaml inference.vllm_asr.service.nodePort). The standalone docker run command in step 3a above maps the container's port 8000 directly to host port 8000 instead — there is no local-Docker equivalent of the chart's NodePort.

For the canonical inventory of every model, image source, and deployment style (CPU vs ROCm, custom sidecar vs official vLLM image, student vs teacher LLM), see models-and-inference.md.

Environment Configuration¶

Create .env file in the workspace root:

cat > .env <<EOF
LOG_LEVEL=DEBUG

# Tenant ID is per-request (in A2A task payload), not an env var

# Backend (Vespa) — read by BootstrapConfig, REQUIRED
BACKEND_URL=http://localhost
BACKEND_PORT=8080

# Phoenix OTLP endpoint (gRPC)
TELEMETRY_OTLP_ENDPOINT=localhost:4317

# Optional pre-existing test LM endpoint; tests accept it only when /v1/models
# advertises the exact production primary model, otherwise they provision one
TEST_LLM_API_BASE=http://localhost:29110/v1
TEST_LLM_MODEL=google/gemma-4-e4b-it

# JAX (for X-CLIP)
JAX_PLATFORM_NAME=cpu
EOF

Multi-Tenant Note: Each tenant uses schema-per-tenant isolation in Vespa. The system automatically creates isolated schemas per tenant.

Multi-Modal Support: Cogniverse supports six content types:

• VIDEO: Frame-based (ColPali) and chunk-based (X-CLIP) processing

• AUDIO: Speech and audio analysis extracted from video

• IMAGE: Visual similarity search with ColQwen3 or ColPali

• DOCUMENT: PDF, DOCX processing with vision models

• TEXT: Natural language processing with text embeddings

• DATAFRAME: Tabular data (CSV, Excel) with text representation

Post-Installation Setup¶

1. Verify Workspace Installation¶

# List installed packages
uv pip list | grep cogniverse

# Expected output (all 12 workspace packages):
# cogniverse-agents               0.1.0
# cogniverse-cli                  0.1.0
# cogniverse-core                 0.1.0
# cogniverse-evaluation           0.1.0
# cogniverse-finetuning           0.1.0
# cogniverse-foundation           0.1.0
# cogniverse-messaging            0.1.0
# cogniverse-runtime              0.1.0
# cogniverse-sdk                  0.1.0
# cogniverse-synthetic            0.1.0
# cogniverse-telemetry-phoenix    0.1.0
# cogniverse-vespa                0.1.0

2. Deploy Vespa Schemas¶

# Deploy ColPali frame-based schema
JAX_PLATFORM_NAME=cpu uv run python scripts/deploy_json_schema.py \
  configs/schemas/video_colpali_smol500_mv_frame_schema.json

# Deploy additional schemas
JAX_PLATFORM_NAME=cpu uv run python scripts/deploy_json_schema.py \
  configs/schemas/video_xclip_sv_chunk_6s_schema.json

3. Download Test Dataset¶

Sample videos, QA pairs, and captions for the evaluation suite live under data/testset/, which is in .gitignore (files are not tracked). The script needs curl, unzip, python3, and uv (already installed in step 2); it pulls QA from HuggingFace and uses range-based extraction to fetch only the test videos it needs from a 11 GB benchmark zip.

Fetch the data with the bundled script:

# Minimal: 13 test videos + QA + captions (~210 MB) — enough for e2e / ingestion tests
./scripts/download_test_data.sh --test-only

# Full Video-ChatGPT benchmark from HuggingFace (~11 GB)
./scripts/download_test_data.sh

# QA + captions only, no videos
./scripts/download_test_data.sh --no-videos

Without this step, fixture-gated tests (tests/e2e/, ingestion integration) will pytest.skip on missing files such as data/testset/evaluation/sample_videos/v_-nl4G-00PtA.mp4.

4. Start the Runtime Server & Register a Tenant¶

There is no default tenant — every tenant, including one named default, must be created via POST /admin/tenants before ingestion or search will accept its tenant_id. That endpoint is served by the runtime, so start it first:

# Start the FastAPI runtime (foreground; use --reload during development)
JAX_PLATFORM_NAME=cpu uv run uvicorn cogniverse_runtime.main:app --port 8000 &

# Register the "default" tenant used by the ingestion command below
curl -X POST http://localhost:8000/admin/tenants \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "default", "created_by": "setup-guide"}'

5. Run Test Ingestion¶

# Ingest sample videos into the tenant registered above
JAX_PLATFORM_NAME=cpu uv run python scripts/run_ingestion.py \
  --video_dir data/testset/evaluation/sample_videos \
  --backend vespa \
  --profile video_colpali_smol500_mv_frame \
  --tenant-id default

6. Verify End-to-End¶

# Run comprehensive test suite
JAX_PLATFORM_NAME=cpu timeout 7200 uv run pytest \
  tests/memory/ \
  tests/ingestion/ \
  tests/evaluation/ \
  tests/routing/ \
  -v --tb=line

Troubleshooting¶

Vespa Connection Issues¶

# Check Vespa health
curl http://localhost:8080/state/v1/health

# Restart Vespa
docker restart vespa

# Check logs
docker logs vespa

Phoenix Not Recording Spans¶

# Check Phoenix is running
docker ps | grep phoenix

# Verify endpoint (set in .env — see Environment Configuration above)
echo $TELEMETRY_OTLP_ENDPOINT

# Check Phoenix logs
docker logs phoenix

Ollama Model Issues¶

# List installed models
docker exec ollama ollama list

# Remove and re-pull model
docker exec ollama ollama rm gemma3:4b
docker exec ollama ollama pull gemma3:4b

Advanced Installation Options¶

Installing Individual Packages¶

# Install only core package
cd libs/core
uv pip install -e .

# Install agents package (automatically installs core as dependency)
cd libs/agents
uv pip install -e .

# Install all workspace packages (dev group, including cogniverse-cli,
# is installed by default). `--all-extras` is NOT valid here: the cpu/
# cuda/rocm torch extras are declared mutually exclusive in
# `[tool.uv] conflicts`, so pick one with `scripts/install_with_gpu.sh`
# or `uv sync --extra <cpu|cuda|rocm>` (see "PyTorch backend selection").
uv sync

Development Installation¶

# Same as above — the `dev` dependency group is a default group, so a
# plain `uv sync` already installs ruff/mypy/pytest-playwright/etc.
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run code quality checks
uv run ruff check .
uv run ruff format .

Package Import Verification¶

# Verify package imports work correctly for all 12 workspace packages
uv run python -c "
# Foundation Layer
from cogniverse_sdk.interfaces.backend import Backend
from cogniverse_sdk.document import Document
from cogniverse_foundation.config.unified_config import SystemConfig
from cogniverse_foundation.telemetry.providers.base import TelemetryProvider

# Core Layer
from cogniverse_core.agents.base import AgentBase
from cogniverse_evaluation.providers import get_evaluation_provider
from cogniverse_telemetry_phoenix.provider import PhoenixProvider

# Implementation Layer
from cogniverse_agents.orchestrator_agent import OrchestratorAgent
from cogniverse_vespa.vespa_schema_manager import VespaSchemaManager
from cogniverse_synthetic.service import SyntheticDataService

# Application Layer
from cogniverse_runtime.main import app
from cogniverse_cli.main import cli
from cogniverse_messaging.gateway import MessagingGateway

print('All 12 workspace packages imported successfully!')
"

Workspace Management¶

Adding New Dependencies¶

# Add dependency to core package
cd libs/core
uv add <package-name>

# Add dependency to agents package
cd libs/agents
uv add <package-name>

# Sync workspace after changes
cd ../..
uv sync

Updating Dependencies¶

# Update all packages
uv sync --upgrade

# Update specific package
uv pip install --upgrade <package-name>

# Regenerate lockfile
uv lock --upgrade

Building Distribution Packages¶

# Build all packages
for dir in libs/*/; do
  (cd "$dir" && uv build)
done

# Build specific package
cd libs/core
uv build

# Output: dist/cogniverse_core-0.1.0-py3-none-any.whl

Common Import Patterns¶

After installation, use these import patterns for all 12 workspace packages:

# ===== FOUNDATION LAYER =====
# SDK - Interfaces and Document Model
from cogniverse_sdk.interfaces.backend import Backend
from cogniverse_sdk.interfaces.config_store import ConfigStore
from cogniverse_sdk.document import Document, ContentType, ProcessingStatus

# Foundation - Configuration and Telemetry
from cogniverse_foundation.config.unified_config import SystemConfig, TenantConfig
from cogniverse_foundation.telemetry.providers.base import TelemetryProvider
from cogniverse_foundation.telemetry.config import TelemetryConfig

# ===== CORE LAYER =====
# Core - Base Classes and Registries
from cogniverse_core.agents.base import AgentBase
from cogniverse_agents.memory_aware_mixin import MemoryAwareMixin
from cogniverse_core.registries.agent_registry import AgentRegistry
from cogniverse_core.common.tenant_utils import parse_tenant_id, get_tenant_storage_path

# Evaluation - Experiment Tracking and Metrics
from cogniverse_evaluation.core.experiment_tracker import ExperimentTracker
from cogniverse_evaluation.metrics.custom import calculate_mrr, calculate_ndcg
from cogniverse_evaluation.evaluators.reference_free import (
    ResultDiversityEvaluator,
    TemporalCoverageEvaluator,
)
from cogniverse_evaluation.providers.registry import EvaluationRegistry

# Telemetry Phoenix - Phoenix Provider (Plugin)
from cogniverse_telemetry_phoenix.provider import PhoenixProvider

# ===== IMPLEMENTATION LAYER =====
# Agents - Orchestration and Search
from cogniverse_agents.orchestrator_agent import OrchestratorAgent, OrchestratorDeps
from cogniverse_agents.search_agent import SearchAgent, SearchAgentDeps
from cogniverse_core.registries.agent_registry import AgentRegistry

# Vespa - Backend and Schema Management
from cogniverse_vespa.vespa_schema_manager import VespaSchemaManager
from cogniverse_vespa.search_backend import VespaSearchBackend
from cogniverse_vespa.json_schema_parser import JsonSchemaParser

# Synthetic - Data Generation
from cogniverse_synthetic.service import SyntheticDataService
from cogniverse_synthetic.generators.base import BaseGenerator
from cogniverse_synthetic.generators.profile import ProfileGenerator
from cogniverse_synthetic.generators.routing import RoutingGenerator
from cogniverse_synthetic.generators.workflow import WorkflowGenerator

# Finetuning - Model Fine-tuning (if used)
# from cogniverse_finetuning import ...

# ===== APPLICATION LAYER =====
# Runtime - Server and Ingestion
from cogniverse_runtime.main import app
from cogniverse_runtime.ingestion.pipeline import VideoIngestionPipeline

# CLI - the `cogniverse` command (installed via the `dev` dependency group)
from cogniverse_cli.main import cli

# Messaging - gateway + runtime client for chat-platform integrations
from cogniverse_messaging.gateway import MessagingGateway
from cogniverse_messaging.runtime_client import RuntimeClient

Workspace & Import Troubleshooting¶

Workspace Issues¶

# Clear UV cache
uv cache clean

# Reinstall workspace
rm -rf .venv uv.lock
uv sync

# Verify package locations
uv pip show cogniverse-core
uv pip show cogniverse-agents

Import Errors¶

If you see ModuleNotFoundError: No module named 'cogniverse_core':

# Ensure you're using the workspace virtual environment
# (Linux/x86_64 or macOS arm64 — Windows is not a supported target,
# see Prerequisites > System Requirements above)
source .venv/bin/activate

# Verify packages are installed
uv pip list | grep cogniverse

# Reinstall in editable mode
uv sync

Path Issues¶

If imports don't work, check your Python path:

import sys
print('\n'.join(sys.path))

# Should include paths like:
# /path/to/cogniverse/libs/core
# /path/to/cogniverse/libs/agents

Next Steps¶

• SDK Architecture: See docs/architecture/sdk-architecture.md
• Multi-Tenant Setup: See docs/architecture/multi-tenant.md
• Configuration: See docs/operations/configuration.md
• Deployment: See docs/operations/deployment.md