Skip to content

AGENTS.md

Latest commit

 

History

History
150 lines (99 loc) · 3.76 KB

AGENTS.md

File metadata and controls

150 lines (99 loc) · 3.76 KB
Raw

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository. This file is symlinked to CLAUDE.md, GEMINI.md and .cursorrules to be automatically read by AI coding assistants.

Project Overview

The Allocator Bot is a portfolio optimization copilot for OpenBB Workspace that provides AI-powered asset allocation recommendations using modern portfolio theory and efficient frontier algorithms.

Development Commands

Installation & Setup

Development installation

uv sync --extra dev

Production installation

pip install git+https://github.com/piiq/allocator-bot.git

Running the Application

openbb-api --app allocator_bot.__main__:get_app --factory

Testing & Code Quality

Run tests

uv run pytest

Code formatting

uv run ruff format .

Linting

uv run ruff check .

Type checking

uv run ty check .

Dependency Management

  • Always use UV commands - never edit pyproject.toml directly
  • Add dependencies: uv add package-name
  • Add dev dependencies: uv add --group dev package-name
  • Sync dependencies: uv sync --extra dev

Architecture Overview

Core Data Flow

User Request → FastAPI Endpoint (/v1/query) → Agent Execution Loop → Portfolio Optimization → SSE Stream Response

Technology Stack

  • Web Framework: FastAPI with Server-Sent Events (SSE)
  • AI/LLM: Magentic library with OpenRouter integration (DeepSeek Chat v3)
  • Portfolio Optimization: PyPortfolioOpt for efficient frontier calculations
  • Data Source: OpenBB Platform for financial market data
  • Package Management: UV for fast Python dependency management

Integration Patterns

OpenBB Workspace Integration

  • Copilot interface at /v1/query endpoint
  • Widget interface at /widgets.json programmatically generated by openbb-api launcher
  • Widget configuration embedded in OpenAPI specifications via openapi_extra
  • Bearer token authentication pattern

Storage Architecture

  • Hybrid approach: Local file storage with optional S3 cloud storage
  • Environment-driven: S3 enabled via S3_ENABLED environment variable
  • Graceful fallback: Falls back to local storage when S3 unavailable

Key Development Patterns

Async/Streaming Architecture

  • Full async/await pattern for all LLM interactions
  • Server-Sent Events for real-time user feedback
  • Streaming responses with progress indicators

Data Validation

  • Strict Pydantic models for all data structures
  • Field-level validation with custom validators
  • Type safety throughout the application

AI Integration

  • Multi-step LLM workflow: task detection → structure parsing → execution
  • Function-free approach with explicit logic exposure to LLM
  • Retry mechanisms for LLM reliability

Configuration

Required Environment Variables

  • OPENROUTER_API_KEY: LLM access via OpenRouter
  • FMP_API_KEY: Financial data via Financial Modeling Prep
  • S3_*: Cloud storage configuration (if S3_ENABLED=true)
  • AGENT_HOST_URL: Application host URL
  • APP_API_KEY: API access token
  • AGENT_MODEL: The model slug used by the agent (optional, defaults to qwen/qwen3.5-397b-a17b)

Optional Configuration

  • DATA_FOLDER_PATH: Local storage path (default: "data")

Deployment

Docker

  • Multi-stage Dockerfile using UV for optimized builds
  • Runs on port 4299
  • Non-root user for security

Kubernetes

  • Complete manifests in /k8s/ directory
  • Separate ConfigMap for non-sensitive variables
  • Secret template for sensitive environment variables

Testing Strategy

  • Unit tests for core portfolio functions
  • Mocking for external dependencies (OpenBB, S3)
  • Integration tests for storage systems
  • Located in /tests/ with pytest framework