Configuration System#

📖 Configuration Architecture Guide

For a comprehensive guide to the YAML configuration system, self-contained architecture, and best practices, see Configuration Architecture.

This page provides the complete reference for all configuration sections and the Python API for accessing configuration at runtime.

Configuration system with YAML loading, environment resolution, and seamless LangGraph integration.

Core Classes#

ConfigBuilder#

class osprey.utils.config.ConfigBuilder(config_path=None)[source]#

Bases: object

Configuration builder with clean, modern architecture.

Features: - Single-file YAML loading with validation and error handling - Environment variable resolution - Pre-computed nested dictionaries for performance - Explicit fail-fast behavior for required configurations - Flat structure supporting framework + application settings via unique naming

Initialize configuration builder.

Parameters:: config_path (str | None) – Path to the config.yml file. If None, looks in current directory.
Raises:: FileNotFoundError – If config.yml is not found and no path is provided.

Main configuration builder with YAML loading, environment resolution, and LangGraph integration.

__init__(config_path=None)[source]#

Initialize configuration builder.

Parameters:: config_path (str | None) – Path to the config.yml file. If None, looks in current directory.
Raises:: FileNotFoundError – If config.yml is not found and no path is provided.

get(path, default=None)[source]#

Get configuration value using dot notation path.

Return type:: Any

Primary Access Functions#

New in v0.7.7: Multi-Project Support

All configuration functions now accept an optional config_path parameter to explicitly specify which project’s configuration to load. This enables multi-project workflows where you can work with multiple projects simultaneously.

Common pattern:

from osprey.utils.config import get_model_config

# Use specific project's config
model = get_model_config("orchestrator", config_path="~/project/config.yml")

# Default behavior (searches current directory)
model = get_model_config("orchestrator")

See Configuration Architecture for complete multi-project workflow documentation.

osprey.utils.config.get_config_value(path, default=None, config_path=None)[source]#

Get a specific configuration value by dot-separated path.

This function provides context-aware access to configuration values, working both inside and outside LangGraph execution contexts. Optionally, an explicit configuration file path can be provided.

Parameters:

path (str) – Dot-separated configuration path (e.g., “execution.timeout”)
default (Any) – Default value to return if path is not found
config_path (str | None) – Optional explicit path to configuration file

Returns:

The configuration value at the specified path, or default if not found

Raises:

ValueError – If path is empty or None

Return type:

Any

Examples

>>> timeout = get_config_value("execution.timeout", 30)
>>> debug_mode = get_config_value("development.debug", False)

>>> # With explicit config path
>>> timeout = get_config_value("execution.timeout", 30, "/path/to/config.yml")

Multi-Project Usage:

# Get value from specific project
value = get_config_value(
    "models.orchestrator.provider",
    config_path="/path/to/project/config.yml"
)

osprey.utils.config.get_full_configuration(config_path=None)[source]#

Get the complete configuration dictionary.

This function provides access to the entire configurable dictionary, working both inside and outside LangGraph execution contexts. Optionally, an explicit configuration file path can be provided.

When an explicit config_path is provided, it is also set as the default configuration so that subsequent config access without explicit path will use this configuration.

Parameters:: config_path (str | None) – Optional explicit path to configuration file. If provided, loads configuration from this path and sets it as the default.
Returns:: Complete configuration dictionary with all configurable values
Return type:: dict[str, Any]

Examples

>>> # Default configuration (backward compatible)
>>> config = get_full_configuration()
>>> user_id = config.get("user_id")
>>> models = config.get("model_configs", {})

>>> # Explicit configuration path (also becomes default)
>>> config = get_full_configuration("/path/to/my-config.yml")
>>> models = config.get("model_configs", {})
>>> # Subsequent calls without path use this config
>>> other_value = get_config_value("some.setting")

Multi-Project Usage:

# Load complete config from specific project
config = get_full_configuration(config_path="~/my-agent/config.yml")

osprey.utils.config.get_agent_dir(sub_dir, host_path=False)[source]#

Get the target directory path within the agent data directory using absolute paths.

Parameters:

sub_dir (str) – Subdirectory name (e.g., ‘user_memory_dir’, ‘execution_plans_dir’)
host_path (bool) – If True, force return of host filesystem path even when running in container

Returns:

Absolute path to the target directory

Return type:

str

Multi-Project Usage:

# Get agent directory for specific project
agent_dir = get_agent_dir(config_path="~/my-agent/config.yml")

Specialized Configuration Functions#

Model and Provider Access#

osprey.utils.config.get_model_config(model_name, config_path=None)[source]#

Get model configuration with automatic context detection.

Works both inside and outside LangGraph contexts. All models are configured at the top level in the ‘models’ section.

Parameters:

model_name (str) – Name of the model (e.g., ‘orchestrator’, ‘classifier’, ‘time_parsing’, ‘response’, ‘approval’, ‘memory’, ‘task_extraction’, ‘python_code_generator’)
config_path (str | None) – Optional explicit path to configuration file for multi-project workflows

Returns:

Dictionary with model configuration containing provider, model_id, and optional settings

Return type:

dict[str, Any]

Examples

Default config (searches current directory):

>>> get_model_config("orchestrator")
{'provider': 'anthropic', 'model_id': 'claude-3-5-sonnet-20241022', ...}

Multi-project workflow:

>>> get_model_config("orchestrator", config_path="~/other-project/config.yml")
{'provider': 'openai', 'model_id': 'gpt-4o', ...}

Configuration format (config.yml):

models:

orchestrator:: provider: anthropic model_id: claude-3-5-sonnet-20241022
classifier:: provider: anthropic model_id: claude-3-5-haiku-20241022

osprey.utils.config.get_provider_config(provider_name, config_path=None)[source]#

Get API provider configuration with automatic context detection.

Parameters:

provider_name (str) – Name of the provider (e.g., ‘openai’, ‘anthropic’)
config_path (str | None) – Optional explicit path to configuration file

Returns:

Dictionary with provider configuration

Return type:

dict[str, Any]

Service Configuration#

osprey.utils.config.get_framework_service_config(service_name, config_path=None)[source]#

Get framework service configuration with automatic context detection.

Parameters:

service_name (str) – Name of the framework service
config_path (str | None) – Optional explicit path to configuration file

Returns:

Dictionary with service configuration

Return type:

dict[str, Any]

osprey.utils.config.get_application_service_config(app_name, service_name)[source]#

Get application service configuration with automatic context detection.

Return type:: dict[str, Any]

Runtime Information#

osprey.utils.config.get_session_info()[source]#

Get session information with automatic context detection.

Return type:: dict[str, Any]

osprey.utils.config.get_interface_context()[source]#

Get interface context indicating which user interface is being used.

The interface context determines how responses are formatted and which features are available (e.g., figure rendering, notebook links, command buttons).

Returns:

The interface type, one of:

”openwebui”: Open WebUI interface with rich rendering capabilities
”cli”: Command-line interface with text-only output
”unknown”: Interface type not detected or not set

Return type:

str

Example

>>> interface = get_interface_context()
>>> if interface == "openwebui":
...     print("Rich UI features available")

Note

This is set automatically by each interface implementation during initialization. The value is used by response generators to provide interface-appropriate guidance about figures, notebooks, and executable commands.

osprey.utils.config.get_current_application()[source]#

Get current application with automatic context detection.

Return type:: str | None

osprey.utils.config.get_execution_limits()[source]#

Get execution limits with automatic context detection.

Return type:: dict[str, Any]

osprey.utils.config.get_agent_control_defaults()[source]#

Get agent control defaults with automatic context detection.

Return type:: dict[str, Any]

osprey.utils.config.get_classification_config()[source]#

Get classification configuration with sensible defaults.

Controls parallel LLM-based capability classification to prevent API flooding while maintaining reasonable performance during task analysis.

Returns:: Dictionary with classification configuration including concurrency limits
Return type:: dict[str, Any]

Examples

>>> config = get_classification_config()
>>> max_concurrent = config.get('max_concurrent_classifications', 5)

Development Utilities#

osprey.utils.config.get_pipeline_config(app_name=None)[source]#

Get pipeline configuration with automatic context detection.

Return type:: dict[str, Any]

Internal Implementation#

osprey.utils.config._get_config(config_path=None, set_as_default=False)[source]#

Get configuration instance (singleton pattern with optional explicit path).

This function supports two modes: 1. Default singleton: When no config_path provided, uses CONFIG_FILE env var or cwd/config.yml 2. Explicit path: When config_path provided, caches and returns config for that specific path

Parameters:

config_path (str | None) – Optional explicit path to configuration file. If provided, this path is used instead of the default singleton behavior.
set_as_default (bool) – If True and config_path is provided, also set this config as the default singleton so future calls without config_path use it.

Returns:

ConfigBuilder instance for the specified or default configuration

Return type:

ConfigBuilder

Examples

>>> # Default singleton behavior (backward compatible)
>>> config = _get_config()

>>> # Explicit config path
>>> config = _get_config("/path/to/config.yml")

>>> # Explicit path that becomes the default
>>> config = _get_config("/path/to/config.yml", set_as_default=True)

osprey.utils.config._get_configurable(config_path=None, set_as_default=False)[source]#

Get configurable dict with automatic context detection.

This function supports both LangGraph execution contexts and standalone execution, with optional explicit configuration path support.

Parameters:

config_path (str | None) – Optional explicit path to configuration file
set_as_default (bool) – If True and config_path is provided, set as default config

Returns:

Complete configuration dictionary with all configurable values

Return type:

dict[str, Any]

Configuration Sections Reference#

This section provides a complete reference for all configuration sections available in the Osprey Framework.

📖 Understanding Configuration Architecture

Before diving into specific sections, review Configuration Architecture to understand:

The self-contained configuration approach
Configuration templates and project initialization
Environment variable integration
Best practices for configuration organization

Configuration Sections#

All configuration is contained in a single config.yml file at the project root.

build_dir#

Type: String

Location: Root config.yml

Default: ./build

Purpose: Specifies the directory where container build files are generated.

build_dir: ./build

Details:

Used by container management system
Contains generated Docker Compose files
Should be in .gitignore
Can use environment variables: ${BUILD_DIR}

project_name#

Type: String

Location: Root config.yml

Default: Derived from project_root path if not specified

Purpose: Canonical identifier for the project/agent.

project_name: "weather-agent"

Details:

First-class attribute for project identification
Used for container labels (Docker/Podman metadata)
Enables multi-project container management
Shown in osprey deploy status output
Separate from pipeline.name (which is for OpenWebUI display)
Falls back to extracting from project_root path if not specified

New in v0.8.2: Container Project Tracking

The project_name attribute enables tracking which project owns deployed containers using Docker labels. All containers are automatically labeled with osprey.project.name for easy identification and filtering.

project_root#

Type: String

Location: Root config.yml

Default: None (must be specified)

Purpose: Absolute path to project root directory.

project_root: ${PROJECT_ROOT}
# Or hard-coded:
project_root: /home/user/my-project

Details:

Required for all path resolution
Use environment variable for portability across machines
Must be absolute path
Used by container management and execution systems

registry_path#

Type: String

Location: Root config.yml

Default: None (must be specified)

Purpose: Path to the application’s registry module.

registry_path: ./src/my_app/registry.py

Details:

Points to the Python module that registers capabilities and context types
Path is relative to project root
Must contain a registry.py file with capability and context registrations
Required for framework to discover application capabilities

Approval Configuration#

Controls human approval workflows and safety policies.

approval.global_mode#

Type: String (enum)

Location: Root config.yml (operator control)

Default: "selective"

Options: "disabled" | "selective" | "all_capabilities"

Purpose: System-wide approval policy.

approval:
  global_mode: "selective"

Values:

disabled - No approval required for any operations
selective - Approval based on capability-specific settings
all_capabilities - All capability executions require approval

approval.capabilities.python_execution#

Type: Object

Location: Root config.yml

Purpose: Controls approval for Python code generation and execution.

approval:
  capabilities:
    python_execution:
      enabled: true
      mode: "epics_writes"

Fields:

enabled (boolean)

Whether Python execution capability is available

true - Python capability can be used
false - Python capability disabled

mode (string)

When to require approval:

"disabled" - No approval required
"epics_writes" - Approve only code that writes to EPICS
"all_code" - Approve all Python code execution

Example:

# In config.yml (root)
approval:
  capabilities:
    python_execution:
      enabled: true
      mode: "epics_writes"  # Approve only EPICS write operations

approval.capabilities.memory#

Type: Object

Location: Root config.yml

Purpose: Controls approval for memory operations.

approval:
  capabilities:
    memory:
      enabled: true

Fields:

enabled (boolean)

true - Memory storage and retrieval allowed
false - Memory operations disabled

Execution Control#

Runtime behavior configuration and safety limits.

execution_control.epics.writes_enabled#

Type: Boolean

Location: Root config.yml (operator control)

Default: false

Purpose: Master switch for EPICS hardware write operations.

execution_control:
  epics:
    writes_enabled: false

Details:

true - EPICS write operations can execute (production mode)
false - All EPICS writes blocked (safe default for development)
Operator-level safety control
Independent of approval settings

execution_control.agent_control#

Type: Object

Location: Root config.yml

Purpose: Performance bypass settings for agent processing.

execution_control:
  agent_control:
    task_extraction_bypass_enabled: false
    capability_selection_bypass_enabled: false

Fields:

task_extraction_bypass_enabled (boolean)

Skip LLM-based task extraction

false (default) - Use LLM to extract structured tasks
true - Pass full conversation history (faster but less precise)
Can be overridden at runtime with /task:off command

capability_selection_bypass_enabled (boolean)

Skip LLM-based capability classification

false (default) - Use LLM to select relevant capabilities
true - Activate all registered capabilities (faster but less efficient)
Can be overridden at runtime with /caps:off command

Use Cases:

Development: Enable bypasses for faster iteration
Production: Keep disabled for optimal performance
R&D: Enable when exploring with small capability sets

execution_control.limits#

Type: Object

Location: Root config.yml

Purpose: Safety limits and execution constraints.

execution_control:
  limits:
    max_reclassifications: 1
    max_planning_attempts: 2
    max_step_retries: 3
    max_execution_time_seconds: 3000
    graph_recursion_limit: 100
    max_concurrent_classifications: 5

Fields:

max_reclassifications (integer)

Maximum number of reclassifications allowed

Default: 1 (allows 1 reclassification, meaning 2 total classification attempts)
Prevents infinite reclassification loops
Counter only increments when reclassification actually occurs, not on initial classification

max_planning_attempts (integer)

Maximum orchestrator planning attempts

Default: 2
Fails task if planning repeatedly fails

max_step_retries (integer)

Maximum retries per execution step

Default: 0
Applies to retriable errors only

max_execution_time_seconds (integer)

Maximum total execution time

Default: 300 (5 minutes)
Prevents runaway executions

graph_recursion_limit (integer)

LangGraph recursion limit

Default: 100
Prevents infinite state graph loops

max_concurrent_classifications (integer)

Maximum concurrent LLM classification requests

Default: 5
Controls parallel capability classification to prevent API flooding
Balances performance with API rate limits
Higher values = faster classification but more API load

System Configuration#

Infrastructure-wide settings.

system.timezone#

Type: String

Location: Root or framework config.yml

Default: America/Los_Angeles

Purpose: Timezone for all framework services and containers.

system:
  timezone: ${TZ:-America/Los_Angeles}

Details:

Uses standard timezone names (e.g., America/New_York, Europe/London)
Ensures consistent timestamps across all components
Propagated to all containers
Can use environment variable for host timezone: ${TZ}

File Paths Configuration#

Controls agent data directory structure.

file_paths.agent_data_dir#

Type: String

Location: Root config.yml

Default: _agent_data

Purpose: Parent directory for all agent-related data.

file_paths:
  agent_data_dir: _agent_data

Details:

All agent data subdirectories are relative to this
Created automatically if doesn’t exist
Should be in .gitignore for development

file_paths Subdirectories#

Type: Strings

Location: Root config.yml

Purpose: Subdirectories within agent_data_dir.

file_paths:
  agent_data_dir: _agent_data
  executed_python_scripts_dir: executed_scripts
  execution_plans_dir: execution_plans
  user_memory_dir: user_memory
  registry_exports_dir: registry_exports
  prompts_dir: prompts
  checkpoints: checkpoints

Subdirectories:

executed_python_scripts_dir: Stores Python code executed by the framework
execution_plans_dir: Stores orchestrator execution plans (JSON)
user_memory_dir: Stores user memory data
registry_exports_dir: Stores exported registry information
prompts_dir: Stores generated prompts when debug enabled
checkpoints: Stores LangGraph checkpoints for conversation state

Application-Specific Paths:

Applications can add their own paths:

# In src/applications/als_assistant/config.yml
file_paths:
  launcher_outputs_dir: launcher_outputs

Deployed Services#

Controls which containers are started.

deployed_services#

Type: List of strings

Location: Root, framework, or application config.yml

Default: []

Purpose: Specifies which services to deploy when running container management.

deployed_services:
  # Framework infrastructure services
  - jupyter
  - open_webui
  - pipelines

  # Application-specific services (optional)
  - mongo          # E.g., MongoDB for ALS Assistant
  - pv_finder      # E.g., PV Finder MCP for ALS Assistant
  - langfuse       # E.g., Observability for ALS Assistant

Service Naming:

Services use simple names that match their configuration keys:

Infrastructure services: jupyter, open_webui, pipelines
Application services: mongo, pv_finder, etc.
Names correspond to keys defined in the services: configuration section

Configuration Structure:

# User project config.yml
deployed_services:
  - jupyter
  - open_webui
  - pipelines
  - mongo       # Application-specific service

# All services defined in services: section
services:
  jupyter:
    path: ./services/jupyter
  open_webui:
    path: ./services/open-webui
  pipelines:
    path: ./services/pipelines
  mongo:
    path: ./services/mongo

Details:

Services listed in deployed_services must be defined in the services: section
Only listed services will be deployed when running osprey deploy up
Service names are simple strings matching configuration keys
See Container Deployment for complete deployment guide

API Provider Configuration#

Configuration for AI/ML model providers.

api.providers#

Type: Object (nested)

Location: Root config.yml

Purpose: Configuration for external API providers.

api:
  providers:
    cborg:
      api_key: ${CBORG_API_KEY}
      base_url: https://api.cborg.lbl.gov/v1
      timeout: 30

    stanford:
      api_key: ${STANFORD_API_KEY}
      base_url: https://aiapi-prod.stanford.edu/v1

    argo:
      api_key: ${ARGO_API_KEY}
      base_url: https://argo-bridge.cels.anl.gov

    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      base_url: https://api.anthropic.com

   openai:
     api_key: ${OPENAI_API_KEY}
     base_url: https://api.openai.com/v1

   google:
     api_key: ${GOOGLE_API_KEY}
     base_url: https://generativelanguage.googleapis.com/v1beta

    ollama:
      api_key: ollama
      base_url: http://doudna:11434
      host: doudna
      port: 11434

Common Fields:

api_key (string, required)

API authentication key

Use environment variables: ${API_KEY_NAME}
Never hard-code actual keys
For Ollama: use literal string "ollama"

base_url (string, required)

Base URL for API endpoint

Must include protocol (http/https)
No trailing slash
Can use environment variables

timeout (integer, optional)

Request timeout in seconds

Default varies by provider
Increase for slow connections

Provider-Specific Fields:

Ollama:

Additional fields for container networking:

ollama:
  api_key: ollama
  base_url: http://doudna:11434
  host: doudna  # For container access
  port: 11434   # For container access

Security:

Always use environment variables for API keys
Store keys in .env file (add to .gitignore)
Never commit actual keys to version control

Model Configuration#

LLM model assignments for framework and application components.

Framework Models#

Type: Object (nested)

Location: src/osprey/config.yml (defaults), can override in root or application

Purpose: Model configurations for framework infrastructure components.

# In src/osprey/config.yml
framework:
  models:
    orchestrator:
      provider: cborg
      model_id: anthropic/claude-sonnet

    response:
      provider: cborg
      model_id: google/gemini-flash
      max_tokens: 5000

    classifier:
      provider: ollama
      model_id: mistral:7b

    approval:
      provider: ollama
      model_id: mistral:7b

    task_extraction:
      provider: cborg
      model_id: google/gemini-flash
      max_tokens: 1024

    memory:
      provider: cborg
      model_id: google/gemini-flash
      max_tokens: 256

    python_code_generator:
      provider: cborg
      model_id: anthropic/claude-haiku
      max_tokens: 4096

    time_parsing:
      provider: ollama
      model_id: mistral:7b
      max_tokens: 512

Framework Model Roles:

orchestrator: Creates execution plans
response: Generates final user responses
classifier: Classifies tasks and selects capabilities
approval: Analyzes code for approval decisions
task_extraction: Extracts structured tasks from conversations
memory: Processes memory storage/retrieval
python_code_generator: Generates Python code
time_parsing: Parses temporal references

Model Configuration Fields:

provider (string, required)

Provider name (must match api.providers key)

model_id (string, required)

Model identifier

Format varies by provider
Anthropic: anthropic/claude-sonnet
OpenAI: openai/gpt-4
Ollama: mistral:7b

max_tokens (integer, optional)

Maximum output tokens

Not supported by all providers
Default varies by model

Application Models#

Type: Object (nested)

Location: src/applications/{app}/config.yml

Purpose: Application-specific model configurations.

# In src/applications/als_assistant/config.yml
models:
  data_analysis:
    provider: cborg
    model_id: anthropic/claude-sonnet

  machine_operations:
    provider: cborg
    model_id: anthropic/claude-sonnet
    max_tokens: 4096

  data_visualization:
    provider: cborg
    model_id: anthropic/claude-sonnet
    max_tokens: 4096

  pv_finder:
    keyword:
      provider: cborg
      model_id: google/gemini-flash
      max_tokens: 4096
    query_splitter:
      provider: cborg
      model_id: google/gemini-flash
      max_tokens: 4096

Details:

Application defines its own model names
Same configuration format as framework models
Can be deeply nested (e.g., pv_finder.keyword)
Merged with framework models (no conflicts)

Development Configuration#

Development and debugging settings.

development.raise_raw_errors#

Type: Boolean

Location: Root config.yml

Default: false

Purpose: Controls error handling behavior.

development:
  raise_raw_errors: false

Values:

false (production) - Errors wrapped in ExecutionError with user-friendly messages
true (development) - Raw exceptions raised with full stack traces

development.prompts#

Type: Object

Location: Root config.yml

Purpose: Prompt debugging configuration.

development:
  prompts:
    show_all: false
    print_all: true
    latest_only: true

Fields:

show_all (boolean)

Print all prompts to console

true - Display prompts with formatting and separators
false - No console output

print_all (boolean)

Save all prompts to files

true - Save to file_paths.prompts_dir
false - No file output

latest_only (boolean)

File naming strategy

true - Overwrite with latest ({name}_latest.md)
false - Timestamp each file ({name}_YYYYMMDD_HHMMSS.md)

Use Cases:

# Development: See everything
development:
  prompts:
    show_all: true
    print_all: true
    latest_only: false

# Production: Silent
development:
  prompts:
    show_all: false
    print_all: false

development.api_calls#

Type: Object

Location: Root config.yml

Purpose: LLM API call logging configuration for debugging.

development:
  api_calls:
    save_all: false
    latest_only: true
    include_stack_trace: false

Fields:

save_all (boolean)

Log all LLM API calls with complete input/output and metadata

true - Save to _agent_data/api_calls/
false - No API call logging (default)

latest_only (boolean)

File naming strategy

true - Overwrite with latest per function
false - Timestamp each API call

include_stack_trace (boolean)

Include full Python stack trace in log metadata

true - Full call stack for deep debugging
false - Show only immediate caller (default)

See also: Prompt Customization

Logging Configuration#

Logging colors and output control.

logging.rich_tracebacks#

Type: Boolean

Location: Root config.yml

Default: false

Purpose: Enable rich-formatted error tracebacks.

logging:
  rich_tracebacks: false
  show_traceback_locals: false
  show_full_paths: false

Fields:

rich_tracebacks (boolean)

Enable rich formatting

true - Colorized, formatted tracebacks
false - Standard Python tracebacks

show_traceback_locals (boolean)

Show local variables in tracebacks

true - Display all local variables
false - Variables hidden

show_full_paths (boolean)

Path display in tracebacks

true - Full absolute paths
false - Relative paths

logging Colors#

Type: Object (nested)

Location: Framework or application config.yml

Purpose: Customize component logging colors.

# Framework colors (src/osprey/config.yml)
logging:
  framework:
    logging_colors:
      orchestrator: "cyan"
      classifier: "light_salmon1"
      task_extraction: "thistle1"
      python: "light_salmon1"
      respond: "thistle1"

  interface:
    logging_colors:
      cli: "deep_sky_blue1"
      pipeline: "deep_sky_blue1"

# Application colors (src/applications/{app}/config.yml)
logging:
  logging_colors:
    data_analysis: "deep_sky_blue1"
    data_visualization: "dark_turquoise"
    pv_address_finding: "dodger_blue2"

Details:

Uses Rich library color names
Framework component colors under logging.framework.logging_colors
Interface component colors under logging.interface.logging_colors
Application colors under logging.logging_colors
Colors used in console output and logs
Falls back to white if not configured

Available Colors:

See Rich color documentation for full color list.

Service Configuration#

Container service definitions.

Framework Services#

Location: src/osprey/config.yml

Purpose: Define framework infrastructure services.

framework:
  services:
    jupyter:
      path: ./services/osprey/jupyter
      containers:
        read:
          name: jupyter-read
          hostname: jupyter-read
          port_host: 8088
          port_container: 8088
          execution_modes: ["read_only"]
        write:
          name: jupyter-write
          hostname: jupyter-write
          port_host: 8089
          port_container: 8088
          execution_modes: ["write_access"]
      copy_src: true
      render_kernel_templates: true

    open_webui:
      path: ./services/osprey/open-webui
      hostname: appsdev2
      port_host: 8080
      port_container: 8080

    pipelines:
      path: ./services/osprey/pipelines
      port_host: 9099
      port_container: 9099
      copy_src: true
      additional_dirs:
        - interfaces

Service Configuration Fields:

path (string, required)

Directory containing Docker Compose template

name (string, optional)

Container name (defaults to service key)

hostname (string, optional)

Container hostname

port_host (integer, optional)

Host port mapping

port_container (integer, optional)

Container port

copy_src (boolean, optional)

Copy src/ to container

Default: false

additional_dirs (list, optional)

Extra directories to copy

render_kernel_templates (boolean, optional)

Process Jupyter kernel templates

Default: false
Jupyter-specific

containers (object, optional)

Multiple container definitions

For services with multiple containers
Each container has same configuration fields

Application Services#

Location: src/applications/{app}/config.yml

Purpose: Define application-specific services.

# In src/applications/als_assistant/config.yml
services:
  mongo:
    name: mongo
    path: ./services/applications/als_assistant/mongo
    port_host: 27017
    port_container: 27017
    copy_src: true

  pv_finder:
    path: ./services/applications/als_assistant/pv_finder
    name: pv-finder
    port_host: 8051
    port_container: 8051
    copy_src: true

  langfuse:
    path: ./services/applications/als_assistant/langfuse
    name: langfuse
    copy_src: false

Same configuration fields as framework services.

Pipeline Configuration#

OpenWebUI pipeline settings.

pipeline.name#

Type: String

Location: Framework or application config.yml

Purpose: Display name for the pipeline in OpenWebUI.

# In src/applications/als_assistant/config.yml
pipeline:
  name: "ALS Assistant"

Details:

Shown in OpenWebUI interface
Identifies the application/pipeline
Framework default: "Generic AI Agent Framework"

pipeline.startup_hooks#

Type: List of strings

Location: Application config.yml

Purpose: Python functions to run at pipeline startup.

pipeline:
  startup_hooks:
    - "initialization.setup_nltk_resources"
    - "initialization.setup_system_packages"
    - "initialization.setup_pv_finder_resources"

Details:

Functions are called during pipeline initialization
Format: "module_path.function_name"
Module path is relative to application directory
Used for downloading resources, initializing services, etc.

Configuration Examples#

Complete Configuration Example#

# config.yml - Complete, self-contained configuration
project_name: "my-agent"
build_dir: ./build
project_root: ${PROJECT_ROOT}
registry_path: ./src/my_app/registry.py

# Model configuration (8 specialized models)
models:
  orchestrator:
    provider: cborg
    model_id: anthropic/claude-sonnet
  response:
    provider: cborg
    model_id: google/gemini-flash
  # ... other 6 models ...

# Service deployment
deployed_services:
  - jupyter
  - open_webui
  - pipelines

# Safety controls
approval:
  global_mode: "selective"
  capabilities:
    python_execution:
      enabled: true
      mode: "epics_writes"
    memory:
      enabled: true

execution_control:
  epics:
    writes_enabled: false
  agent_control:
    task_extraction_bypass_enabled: false
    capability_selection_bypass_enabled: false
  limits:
    max_reclassifications: 1
    max_planning_attempts: 2
    max_step_retries: 3
    max_execution_time_seconds: 3000
    graph_recursion_limit: 100
    max_concurrent_classifications: 5

system:
  timezone: ${TZ:-America/Los_Angeles}

file_paths:
  agent_data_dir: _agent_data
  executed_python_scripts_dir: executed_scripts
  execution_plans_dir: execution_plans
  user_memory_dir: user_memory
  registry_exports_dir: registry_exports
  prompts_dir: prompts
  checkpoints: checkpoints

deployed_services:
  - jupyter
  - open_webui
  - pipelines
  - mongo
  - pv_finder

development:
  raise_raw_errors: false
  prompts:
    show_all: false
    print_all: true
    latest_only: true

logging:
  rich_tracebacks: false
  show_traceback_locals: false
  show_full_paths: false

api:
  providers:
    cborg:
      api_key: ${CBORG_API_KEY}
      base_url: https://api.cborg.lbl.gov/v1
      timeout: 30
    stanford:
      api_key: ${STANFORD_API_KEY}
      base_url: https://aiapi-prod.stanford.edu/v1
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      base_url: https://api.anthropic.com
    openai:
      api_key: ${OPENAI_API_KEY}
      base_url: https://api.openai.com/v1
    ollama:
      api_key: ollama
      base_url: http://host.containers.internal:11434
      host: host.containers.internal
      port: 11434

Application Configuration Example#

# src/applications/als_assistant/config.yml

file_paths:
  launcher_outputs_dir: launcher_outputs

services:
  pv_finder:
    path: ./services/applications/als_assistant/pv_finder
    name: pv-finder
    port_host: 8051
    port_container: 8051
    copy_src: true

  mongo:
    name: mongo
    path: ./services/applications/als_assistant/mongo
    port_host: 27017
    port_container: 27017
    copy_src: true

models:
  data_analysis:
    provider: cborg
    model_id: anthropic/claude-sonnet

  machine_operations:
    provider: cborg
    model_id: anthropic/claude-sonnet
    max_tokens: 4096

  pv_finder:
    keyword:
      provider: cborg
      model_id: google/gemini-flash
      max_tokens: 4096

pipeline:
  name: "ALS Assistant"
  startup_hooks:
    - "initialization.setup_nltk_resources"
    - "initialization.setup_pv_finder_resources"

logging:
  logging_colors:
    data_analysis: "deep_sky_blue1"
    data_visualization: "dark_turquoise"
    pv_address_finding: "dodger_blue2"