Cogniverse Study Guide: Package Development¶

# Clone repository
git clone <repository-url>
cd cogniverse

# Install uv if not already installed
pip install uv

# Sync entire workspace (all packages in editable mode)
uv sync

# Verify installation
uv pip list | grep cogniverse
# Expected (12 packages in dependency order):
# cogniverse-sdk                   0.1.0
# cogniverse-foundation            0.1.0
# cogniverse-evaluation            0.1.0
# cogniverse-core                  0.1.0
# cogniverse-telemetry-phoenix     0.1.0
# cogniverse-agents                0.1.0
# cogniverse-vespa                 0.1.0
# cogniverse-synthetic             0.1.0
# cogniverse-finetuning            0.1.0
# cogniverse-runtime               0.1.0
# cogniverse-cli                   0.1.0
# cogniverse-messaging             0.1.0

# Activate workspace virtual environment
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

# Verify Python path
which python
# Should point to: /path/to/cogniverse/.venv/bin/python

# Navigate to foundation package
cd libs/foundation

# Add a new dependency
uv add pydantic

# Update existing dependency
uv add --upgrade pydantic

# Remove dependency
uv remove pydantic

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

# Test foundation package
uv run pytest tests/telemetry/ -v

# Navigate to agents package
cd libs/agents

# Add dependency (will automatically install if needed)
uv add litellm

# Since agents depends on core and synthetic, changes to those are immediately available
# Edit code in cogniverse_agents/orchestrator_agent.py
from cogniverse_foundation.config.unified_config import SystemConfig  # Uses editable foundation
from cogniverse_core.registries.backend_registry import BackendRegistry  # Uses editable core

# Run tests for this package only
uv run pytest tests/agents/ -v

# Navigate to synthetic package
cd libs/synthetic

# Add dependencies
uv add faker  # For synthetic data generation

# synthetic depends on sdk, foundation, and core — keep dependencies
# beyond those minimal
from pydantic import BaseModel, Field

# Run tests
uv run pytest tests/synthetic/ -v

# Scenario: Adding a new feature that spans multiple layers

# 1. Start with foundation layer (base types/utilities)
cd libs/foundation
# Edit cogniverse_foundation/telemetry/manager.py
# Add new telemetry capability

# 2. Update evaluation package (core layer) to use new telemetry
cd ../evaluation
# Edit cogniverse_evaluation/core/experiment_tracker.py
from cogniverse_foundation.telemetry.manager import TelemetryManager
telemetry = TelemetryManager()
# Use new telemetry capability

# 3. Update core package (core layer) for business logic
cd ../core
# Edit cogniverse_core/memory/backend_config.py
# Add new configuration field for tenant memory settings

# 4. Update agents package (implementation layer) to use new config
cd ../agents
# Edit cogniverse_agents/orchestrator_agent.py
from cogniverse_foundation.config.unified_config import SystemConfig
from cogniverse_core.registries.backend_registry import BackendRegistry
# Use new tenant memory config

# 5. Update runtime (application layer) to expose new feature
cd ../runtime
# Edit cogniverse_runtime/routers/admin.py or cogniverse_runtime/main.py
# Add endpoint for tenant memory configuration

# 6. Sync workspace to ensure all changes are available
cd ../../..
uv sync

# 7. Run layer-aware tests
# Foundation layer tests
uv run pytest tests/telemetry/ tests/common/ -v

# Core layer tests
uv run pytest tests/evaluation/ tests/memory/ -v

# Implementation layer tests
JAX_PLATFORM_NAME=cpu uv run pytest tests/agents/ tests/synthetic/ -v

# Application layer tests
uv run pytest tests/runtime/ -v

# Run ingestion script
JAX_PLATFORM_NAME=cpu uv run python scripts/run_ingestion.py \
  --video_dir data/testset/evaluation/sample_videos \
  --backend vespa \
  --tenant-id acme_corp

# Open the web client (deployed by `cogniverse up`)
open http://localhost:28400

# Run experiments
uv run python scripts/run_experiments_with_visualization.py \
  --tenant-id acme:acme \
  --dataset-name golden_eval_v1 \
  --profiles frame_based_colpali

# Navigate to specific package
cd libs/core

# Add runtime dependency
uv add httpx

# Add with version constraint
uv add "pydantic>=2.0,<3.0"

# Add optional dependency group
uv add --optional telemetry arize-phoenix-otel

# Add development dependency
uv add --dev pytest-asyncio

# Add dependency used across multiple packages
cd /path/to/cogniverse
uv add ruff  # Code formatter/linter

# Add test dependency for workspace
uv add --dev pytest pytest-cov

cd /path/to/cogniverse
uv sync

# View lockfile (contains exact versions for all 12 packages + dependencies)
cat uv.lock

# Regenerate lockfile (after pyproject.toml changes)
uv lock

# Upgrade all dependencies to latest compatible versions
uv lock --upgrade

# Upgrade specific package
uv add --upgrade pydantic

# Scenario: Multiple packages in different layers require different versions of same dependency

# libs/foundation/pyproject.toml requires: httpx>=0.25.0,<0.26.0
# libs/agents/pyproject.toml requires: httpx>=0.24.0
# libs/runtime/pyproject.toml requires: httpx>=0.25.0

# uv will resolve to: httpx==0.25.x (satisfies all layers)

# If incompatible, uv will report error:
# ERROR: Cannot resolve dependencies:
#   cogniverse-foundation requires httpx>=0.25.0,<0.26.0
#   cogniverse-agents requires httpx>=0.27.0

# Solution: Align version constraints across layers in pyproject.toml files
# Start with foundation layer and propagate upward

# Build all 12 SDK packages for distribution (order matters!)
# Foundation layer first
for dir in libs/sdk libs/foundation; do
  echo "Building $(basename $dir)..."
  (cd "$dir" && uv build)
done

# Core layer
for dir in libs/evaluation libs/core; do
  echo "Building $(basename $dir)..."
  (cd "$dir" && uv build)
done

# Implementation layer
for dir in libs/telemetry-phoenix libs/agents libs/vespa libs/synthetic libs/finetuning; do
  echo "Building $(basename $dir)..."
  (cd "$dir" && uv build)
done

# Application layer (cli and messaging have no cogniverse deps, build anytime)
for dir in libs/runtime libs/cli libs/messaging; do
  echo "Building $(basename $dir)..."
  (cd "$dir" && uv build)
done

# Output (in each libs/*/dist/):
# cogniverse_sdk-0.1.0-py3-none-any.whl
# cogniverse_sdk-0.1.0.tar.gz
# cogniverse_foundation-0.1.0-py3-none-any.whl
# cogniverse_foundation-0.1.0.tar.gz
# ... (all 12 packages)

# Build core package only
cd libs/core
uv build

# Verify build artifacts
ls -lh dist/
# cogniverse_core-0.1.0-py3-none-any.whl
# cogniverse_core-0.1.0.tar.gz

# Inspect wheel contents
unzip -l dist/cogniverse_core-0.1.0-py3-none-any.whl

# Create test environment
python -m venv test_env
source test_env/bin/activate

# Install core package from wheel
pip install libs/core/dist/cogniverse_core-0.1.0-py3-none-any.whl

# Install agents (will automatically install core dependency)
pip install libs/agents/dist/cogniverse_agents-0.1.0-py3-none-any.whl

# Verify imports
python -c "from cogniverse_foundation.config.unified_config import SystemConfig; print('Success!')"

# CORRECT: Install in layer dependency order

# Foundation layer
pip install dist/cogniverse_sdk-0.1.0-py3-none-any.whl
pip install dist/cogniverse_foundation-0.1.0-py3-none-any.whl

# Core layer
pip install dist/cogniverse_evaluation-0.1.0-py3-none-any.whl
pip install dist/cogniverse_core-0.1.0-py3-none-any.whl

# Implementation layer
pip install dist/cogniverse_telemetry_phoenix-0.1.0-py3-none-any.whl
pip install dist/cogniverse_agents-0.1.0-py3-none-any.whl
pip install dist/cogniverse_vespa-0.1.0-py3-none-any.whl
pip install dist/cogniverse_synthetic-0.1.0-py3-none-any.whl
pip install dist/cogniverse_finetuning-0.1.0-py3-none-any.whl

# Application layer
pip install dist/cogniverse_runtime-0.1.0-py3-none-any.whl

# INCORRECT: May fail due to missing dependencies
pip install dist/cogniverse_runtime-0.1.0-py3-none-any.whl  # Needs all lower layers

# Check package metadata
cd libs/core
uv build
pip show cogniverse-core

# Output:
# Name: cogniverse-core
# Version: 0.1.0
# Summary: Core utilities for Cogniverse multi-agent system
# Home-page: https://github.com/yourorg/cogniverse
# Author: Your Name
# License: MIT
# Requires: pydantic, httpx, arize-phoenix-otel
# Required-by: cogniverse-agents, cogniverse-vespa

# Run all core package tests
uv run pytest tests/common/ tests/telemetry/ -v

# Run with coverage
uv run pytest tests/common/ --cov=cogniverse_core --cov-report=html

# View coverage report
open htmlcov/index.html

# Run agents tests
JAX_PLATFORM_NAME=cpu timeout 1800 uv run pytest tests/agents/ -v --tb=line

# Run specific test file
uv run pytest tests/agents/unit/ -v

# Run with markers
uv run pytest tests/agents/ -m "not slow" -v

# Run integration tests (multiple packages)
JAX_PLATFORM_NAME=cpu timeout 7200 uv run pytest \
  tests/memory/ \
  tests/ingestion/integration/ \
  tests/evaluation/ \
  tests/routing/ \
  -v --tb=line

# Update core package version
# libs/core/pyproject.toml
[project]
name = "cogniverse-core"
version = "0.2.0"  # Increment version

# Update agents package (depends on core)
# libs/agents/pyproject.toml
[project]
name = "cogniverse-agents"
version = "0.2.0"
dependencies = [
    "cogniverse-core>=0.2.0",  # Update dependency
]

# Build all packages
for dir in libs/*/; do
  echo "Building $(basename $dir) v0.2.0..."
  (cd "$dir" && uv build)
done

# Create clean test environment
python -m venv release_test_env
source release_test_env/bin/activate

# Install in dependency order
pip install libs/core/dist/cogniverse_core-0.2.0-py3-none-any.whl
pip install libs/vespa/dist/cogniverse_vespa-0.2.0-py3-none-any.whl
pip install libs/agents/dist/cogniverse_agents-0.2.0-py3-none-any.whl

# Run smoke tests
python -c "
from cogniverse_foundation.telemetry.config import TelemetryConfig
from cogniverse_agents.orchestrator_agent import OrchestratorAgent, OrchestratorDeps
from cogniverse_core.registries.agent_registry import AgentRegistry
from cogniverse_foundation.config.utils import create_default_config_manager

from cogniverse_foundation.config.unified_config import LLMEndpointConfig
deps = OrchestratorDeps(
    telemetry_config=TelemetryConfig(),
    llm_config=LLMEndpointConfig(
        model='openai/google/gemma-4-e4b-it',
        api_base='http://localhost:11434/v1',
    ),
)
config_manager = create_default_config_manager()
registry = AgentRegistry(tenant_id='acme', config_manager=config_manager)
agent = OrchestratorAgent(deps, registry, config_manager=config_manager)
print('Release smoke test passed')
"

# Create git tag
git tag -a v0.2.0 -m "Release version 0.2.0"
git push origin v0.2.0

# Publish core package
cd libs/core
uv publish

# Publish other packages (in dependency order)
cd ../vespa && uv publish
cd ../agents && uv publish
cd ../runtime && uv publish

# Maintain >80% coverage for all packages
uv run pytest tests/agents/ --cov=cogniverse_agents --cov-fail-under=80

# ✅ Coverage report:
# cogniverse_agents/orchestrator_agent.py              95%
# cogniverse_agents/search_agent.py                87%
# cogniverse_agents/gateway_agent.py              82%
# TOTAL                                            88%

# Pre-commit checklist
uv run ruff check .                 # Linting
uv run ruff format .                # Formatting
uv run pytest tests/ -v             # All tests
uv build                            # Build verification