AI & Agent¶

Agent construction, model catalog, and runtime configuration. Builds the Pathfinder unified agent with the correct LLM engine and tools.

Overview¶

Agent Factory — Build the unified agent. Select engine (OpenAI, Anthropic, Google), resolve model ID, apply reasoning effort.
Model Catalog — Model metadata, provider mappings, reasoning-effort config. Populates the model picker; enforces sampling constraints.

Note

The default model is openai/gpt-4.1. Override per-request via the model field in the chat request body, or set DEFAULT_MODEL_ID in the environment.

Agent Factory¶

Purpose: Build the Pathfinder unified agent with the correct engine and model selection. Handles per-request overrides and reasoning effort. Resolves model ID from override, persisted state, or server default.

Key functions: create_agent(), resolve_effective_model_id()

Factory helpers for constructing the agent and its engine.

veupath_chatbot.ai.agents.factory.resolve_effective_model_id(*, model_override=None, persisted_model_id=None)[source]¶

Resolve effective model ID from override and persisted state.

Priority: per-request override > persisted per-conversation > server default.

Return type:: str

veupath_chatbot.ai.agents.factory.create_engine(*, provider_override=None, model_override=None, reasoning_effort=None, temperature=None, seed=None, context_size=None, reasoning_budget=None, site_id='plasmodb')[source]¶

Create an LLM engine, optionally overridden per-request.

Return type:: BaseEngine

veupath_chatbot.ai.agents.factory.create_agent(site_id, user_id=None, chat_history=None, strategy_graph=None, selected_nodes=None, *, provider_override=None, model_override=None, reasoning_effort=None, mentioned_context=None, disable_rag=False, temperature=None, seed=None, context_size=None, response_tokens=None, reasoning_budget=None)[source]¶

Create a unified Pathfinder agent instance.

Return type:: PathfinderAgent

Model Catalog¶

Purpose: Model metadata and provider mappings. Which models support reasoning, sampling restrictions (e.g. o1 must use temperature=1). Used to populate the model picker and enforce constraints.

Key types: ModelProvider, ReasoningEffort Key functions: get_model_entry(), build_reasoning_hyperparams()

Central model catalog — single source of truth for available LLM models.

Each entry carries enough metadata for the frontend to render a grouped dropdown and for the backend to validate per-request overrides.

Cloud models are hardcoded. Ollama (local) models are loaded from an optional YAML file pointed to by OLLAMA_MODELS_CONFIG.

class veupath_chatbot.ai.models.catalog.ModelEntry(id, name, provider, model, description='', supports_reasoning=False, context_size=0, default_reasoning_budget=0, input_price=0.0, cached_input_price=0.0, output_price=0.0)[source]¶

Bases: object

A single model in the catalog.

id: str¶

name: str¶

provider: Literal['openai', 'anthropic', 'google', 'ollama', 'mock']¶

model: str¶

description: str¶

supports_reasoning: bool¶

context_size: int¶

default_reasoning_budget: int¶

input_price: float¶

cached_input_price: float¶

output_price: float¶

__init__(id, name, provider, model, description='', supports_reasoning=False, context_size=0, default_reasoning_budget=0, input_price=0.0, cached_input_price=0.0, output_price=0.0)¶

veupath_chatbot.ai.models.catalog.build_reasoning_hyperparams(provider, effort, *, budget_override=None)[source]¶

Return provider-specific hyperparams that implement effort.

Parameters:

provider (Literal['openai', 'anthropic', 'google', 'ollama', 'mock']) – Model provider.
effort (Literal['none', 'low', 'medium', 'high'] | None) – Reasoning effort (default: None).
budget_override (int | None) – Custom reasoning token budget (overrides effort map).

Returns:

Dict of provider-specific hyperparameters, or empty dict.

Return type:

dict[str, object]

veupath_chatbot.ai.models.catalog.get_model_catalog()[source]¶

Return the full model catalog (cloud + local).

Return type:: tuple[ModelEntry, …]

veupath_chatbot.ai.models.catalog.get_model_entry(model_id)[source]¶

Look up a model by catalog ID.

Parameters:: model_id (str) – Model identifier (e.g. openai/gpt-5).
Returns:: Model entry if found, otherwise None.
Return type:: ModelEntry | None

Prompts¶

Purpose: System prompts for the unified agent and sub-kani agents. Prompt templates with site context, strategy state, and tool instructions.

Prompt builders for the main agent.

veupath_chatbot.ai.prompts.executor_prompt.build_agent_system_prompt(*, site_id, selected_nodes, mentioned_context=None)[source]¶

Build the executor agent system prompt.

Parameters:

site_id (str) – VEuPathDB site identifier.
selected_nodes (JSONObject | None) – Selected graph nodes (default: None).
mentioned_context (str | None) – Rich context from @-mentioned entities (default: None).

Returns:

Full system prompt string.

Return type:

str

Prompt loading helpers for the AI agent.

veupath_chatbot.ai.prompts.loader.load_system_prompt()[source]¶

Load and combine the unified system prompt.

Return type:: str

System prompt builder for workbench chat conversations.

veupath_chatbot.ai.prompts.workbench_chat.build_workbench_system_prompt(*, site_id, experiment_context)[source]¶

Build the system prompt for a workbench chat conversation.

Composes shared base prompt (system.md + safety.md + site_hints.md) with workbench-specific instructions and experiment context.

Return type:: str

Model Pricing¶

Purpose: Cost estimation utilities for LLM API calls. Calculates USD cost per request accounting for prompt tokens, completion tokens, and cached token discounts.

Cost estimation utilities for LLM model usage.

veupath_chatbot.ai.models.pricing.estimate_cost(model_id, prompt_tokens, completion_tokens, cached_tokens=0)[source]¶

Estimate USD cost for a model call.

Cached tokens are charged at cached_input_price instead of input_price. Returns 0.0 and logs a warning for unknown models.

Return type:: float