Project Structure and Dependencies

Purpose and Scope

This page documents the Python backend project structure, dependency management system, and the core LargeLanguageModel abstraction layer that enables multi-provider LLM support. This covers the foundational configuration and infrastructure for the FastAPI backend. For details on the FastAPI application itself and its routers, see FastAPI Application. For information about individual service integrations, see Service Integration Routers.

Project Structure Overview

The Python backend is organized as a standard Python package managed by uv, a modern Python package manager. The project root contains configuration files that define dependencies, scripts, and project metadata.

Directory Structure

API Router Organization

The api/main.py file includes 11 routers at specific prefixes:

Sources: api/main.py1-45 routers/__init__.py1-30

Dependency Management with uv

The project uses uv as its package manager, which provides fast dependency resolution and reproducible builds. Dependencies are declared in pyproject.toml and locked in uv.lock.

Project Metadata

pyproject.toml1-6 defines the project metadata:

Core Dependencies

The project has 26 direct dependencies organized by function:

LangChain Ecosystem (AI Orchestration)

Web Framework (API Server)

Data Processing & External Services

Utilities

Sources: pyproject.toml7-28

Entry Point Scripts

The project defines two executable scripts in pyproject.toml28-30:

[project.scripts]
agentic-api-run = "app.run:run"
agentic-mcp = "mcp_server.server:run"

These scripts enable running the application in two modes:

• API Mode: agentic-api-run launches the FastAPI server
• MCP Mode: agentic-mcp launches the Model Context Protocol server

LargeLanguageModel Abstraction Layer

The LargeLanguageModel class in core/llm.py78-194 provides a unified interface for multiple LLM providers, abstracting away provider-specific initialization and API details.

Provider Configuration Architecture

Sources: core/llm.py21-75

Provider-Specific Configuration

The PROVIDER_CONFIGS dictionary at core/llm.py21-75 defines configuration for each provider:

Google (Gemini)

"google": {
    "class": ChatGoogleGenerativeAI,
    "api_key_env": "GOOGLE_API_KEY",
    "default_model": "gemini-2.5-flash",
    "param_map": {"api_key": "google_api_key"},
}

OpenAI

"openai": {
    "class": ChatOpenAI,
    "api_key_env": "OPENAI_API_KEY",
    "default_model": "gpt-5-mini",
    "param_map": {
        "api_key": "openai_api_key",
        "base_url": "base_url",
    },
}

Anthropic (Claude)

"anthropic": {
    "class": ChatAnthropic,
    "api_key_env": "ANTHROPIC_API_KEY",
    "default_model": "claude-4-sonnet",
    "param_map": {
        "api_key": "anthropic_api_key",
        "base_url": "base_url",
    },
}

Ollama (Local Models)

"ollama": {
    "class": ChatOllama,
    "api_key_env": None,  # No API key required
    "base_url_env": "OLLAMA_BASE_URL",
    "default_model": "llama3",
    "param_map": {
        "base_url": "base_url",
    },
}

DeepSeek

"deepseek": {
    "class": ChatOpenAI,  # Uses OpenAI-compatible API
    "api_key_env": "DEEPSEEK_API_KEY",
    "base_url_override": "https://api.deepseek.com/v1",
    "default_model": "deepseek-chat",
    "param_map": {
        "api_key": "openai_api_key",
        "base_url": "base_url",
    },
}

OpenRouter

"openrouter": {
    "class": ChatOpenAI,  # Uses OpenAI-compatible API
    "api_key_env": "OPENROUTER_API_KEY",
    "base_url_override": "https://openrouter.ai/api/v1",
    "default_model": "mistralai/mistral-7b-instruct",
    "param_map": {
        "api_key": "openai_api_key",
        "base_url": "base_url",
    },
}

Sources: core/llm.py21-75

LargeLanguageModel Class Interface

Sources: core/llm.py78-194

Initialization Flow

The __init__ method at core/llm.py79-169 implements a sophisticated initialization flow:

1. Provider Validation core/llm.py98-105: Validates the provider exists in PROVIDER_CONFIGS
2. Model Resolution core/llm.py108-113: Uses provided model or falls back to default
3. API Key Handling core/llm.py121-134: Retrieves API key from parameter or environment
4. Base URL Resolution core/llm.py136-155: Determines base URL from parameter, config override, or environment
5. Client Instantiation core/llm.py159-169: Creates the LangChain chat model instance

Public Methods

generate_text()

core/llm.py171-190

def generate_text(
    self,
    prompt: str,
    system_message: str | None = None,
) -> str

Generates text using the configured LLM:

1. Constructs a message list with optional SystemMessage core/llm.py177-179
2. Adds the user prompt as HumanMessage core/llm.py181
3. Invokes the LLM client core/llm.py184
4. Returns the string content core/llm.py185

summarize_text()

core/llm.py192-193

def summarize_text(self, text: str) -> str

Placeholder method for text summarization. Currently returns a simple truncated summary.

Sources: core/llm.py78-194

Core Module Configuration

The core module provides environment configuration and logging through core/config.py1-26

Configuration Variables

The core/config.py module loads environment variables and exposes configuration:

Logger Configuration

The get_logger(name) function at core/config.py22-25 creates module-specific loggers with the appropriate logging level:

• DEBUG mode: logging.DEBUG for detailed output
• Production mode: logging.INFO for standard logging

Sources: core/config.py1-26

Tool Layer Organization

The tools/ directory contains reusable components that services depend on. Each tool provides specific functionality for external integrations.

Web Search with Tavily

The tools/google_search/seach_agent.py implements web search using the TavilySearch tool from LangChain:

Key components:

• tavily_tool tools/google_search/seach_agent.py11: Global TavilySearch instance
• web_search_pipeline() tools/google_search/seach_agent.py14-62: Main search function with configurable max_results
• Result format: Returns list of dicts with url, md_body_content (mapped from Tavily's content), and title

Sources: tools/google_search/seach_agent.py1-84

Dependency Version Locking

The uv.lock file provides deterministic dependency resolution. It uses a version = 1 lock file format uv.lock1 and specifies requires-python = ">=3.12" uv.lock3

Lock File Structure

Each package entry includes:

• name and version: Package identification
• source: PyPI registry URL or virtual source for the project itself
• dependencies: Resolved dependency list with specific versions
• sdist/wheels: Distribution files with SHA256 hashes for integrity verification

The agentic-browser package itself is listed at uv.lock10-34 with all 26 direct dependencies locked to specific versions.

Sources: uv.lock1-7 uv.lock10-34 uv.lock177-193

Summary

The Python backend project structure follows these principles:

1. Modern Package Management: Uses uv for fast, reproducible dependency resolution
2. Provider Abstraction: The LargeLanguageModel class enables seamless switching between 6 LLM providers
3. Configuration-Driven: All provider-specific details are centralized in PROVIDER_CONFIGS
4. Environment-Based Secrets: API keys and URLs are loaded from environment variables
5. Type Safety: Uses Python 3.12+ type hints and Pydantic for validation
6. Dual Entry Points: Supports both API server and MCP server modes

This foundation enables the rest of the backend to focus on business logic without worrying about LLM provider differences or dependency management complexity.

Sources: pyproject.toml1-31 core/llm.py1-204 core/__init__.py1-15 uv.lock1-55