AI Tools

Tool registration mixins and registries exposed to the agent. These define the catalog, research, validation, and execution tools available during chat. Each tool is an @ai_function() that the LLM can call.

Overview

  • Unified Registry — Combines all tool mixins (catalog, strategy, research, validation, optimization, artifacts) into a single registry for the unified agent.

  • Catalog & Registry — Catalog discovery and graph-building tools.

  • Research Registry — Web search and literature search (shared tools).

  • Execution Tools — Parse tool args, apply graph snapshots, build strategy.

Unified Registry

Purpose: Combined tool registry for the unified agent. Merges the catalog, strategy, research, validation, optimization, and artifact tools into a single mixin so the agent can use all capabilities per-turn.

Unified tool registration mixin — executor + planning tools.

Combines the executor’s graph-building / execution tools with the planner’s research, validation, and optimization tools so a single agent can decide which capabilities to use per turn.

Not included from the planner:

  • DelegationToolsMixin – the unified agent already has delegate_strategy_subtasks, so plan-session delegation drafting/requesting is not applicable.

  • SiteCatalogToolsMixin – duplicate of executor catalog tools.

  • list_saved_planning_artifacts / get_saved_planning_artifact – removed from ArtifactToolsMixin. Artifacts are embedded in strategy messages.

class veupath_chatbot.ai.tools.unified_registry.UnifiedToolRegistryMixin[source]

Bases: ExportToolsMixin, GeneToolsMixin, ExperimentToolsMixin, OptimizationToolsMixin, WorkbenchToolsMixin, ArtifactToolsMixin, AgentToolRegistryMixin

Combined tool registry for the unified agent.

MRO places planner tool mixins first so they can override any shared method names if needed (they don’t currently), and AgentToolRegistryMixin last so its ResearchToolsMixin (web_search, literature_search) is available to all.

Classes using this mixin must provide the same attributes as AgentToolRegistryMixin plus site_id: str.

The _emit_event method (required by OptimizationToolsMixin) is provided by PathfinderAgent which pushes events onto its streaming event_queue.

Catalog & Registry

Purpose: Base tool registry. Provides catalog discovery (record types, searches, parameters), dependent vocab, and graph-building tools. Each tool returns combined RAG + WDK results when both are available.

Key methods (on AgentToolRegistryMixin): list_sites, get_record_types, list_searches, get_search_parameters, get_dependent_vocab, plus strategy tools for create_step, list_current_steps, build_strategy, etc.

Agent tool registration mixin (aggregator).

Composes category-specific mixins into a single AgentToolRegistryMixin that provides all @ai_function methods for the agent.

class veupath_chatbot.ai.tools.registry.AgentToolRegistryMixin[source]

Bases: CatalogToolsMixin, StrategyToolsMixin, ResearchToolsMixin

Mixin for agent tool registration.

Inherits web_search and literature_search from ResearchToolsMixin.

Inherits catalog lookup tools from CatalogToolsMixin.

Inherits strategy, execution, result, and conversation tools from StrategyToolsMixin (auto-delegated to underlying tool instances).

Classes using this mixin must provide these attributes: - site_id: str - catalog_tools: CatalogTools - catalog_rag_tools: CatalogRagTools - example_plans_rag_tools: ExamplePlansRagTools - strategy_tools: StrategyTools - execution_tools: ExecutionTools - result_tools: ResultTools - conversation_tools: ConversationTools - web_search_service: WebSearchService - literature_search_service: LiteratureSearchService

Research Registry

Purpose: Research tools mixin: web search and literature search. Provides web_search and literature_search tools.

Shared research tool mixin (web + literature search).

Used by both PlannerToolRegistryMixin and AgentToolRegistryMixin so that web and literature search are available regardless of conversation mode.

class veupath_chatbot.ai.tools.research_registry.ResearchToolsMixin[source]

Bases: object

Mixin that exposes web and literature search as Kani tools.

Classes using this mixin must provide these attributes:

  • web_search_service: WebSearchService

  • literature_search_service: LiteratureSearchService

web_search_service: WebSearchService = None
literature_search_service: LiteratureSearchService = None

Search the web and return results with citations.

Return type:

JSONObject

Search scientific literature across all sources and return results with citations.

Return type:

JSONObject

Result Tools

Purpose: Tools for retrieving step results from VEuPathDB – sample records, download URLs, and result summaries. Includes WDK error handling for common API failures.

Tools for retrieving step results (sample records, download URLs).

class veupath_chatbot.ai.tools.result_tools.ResultTools(session, strategy_api=None, results_api=None)[source]

Bases: object

Tools for fetching step results from VEuPathDB.

__init__(session, strategy_api=None, results_api=None)[source]
async get_download_url(wdk_step_id, format='csv', attributes=None)[source]

Get a download URL for step results.

The URL can be used to download results in the specified format.

Return type:

JSONObject

async get_sample_records(wdk_step_id, limit=5)[source]

Get a sample of records from an executed step.

Returns the first N records to show the user what data is available.

Return type:

JSONObject

Strategy Tool Registry

Purpose: Strategy, execution, result, and conversation tool delegation mixin. Auto-discovers @ai_function methods on composed tool instances via __getattr__ and __dir__ delegation pattern.

Strategy, execution, result, and conversation tool delegation.

Instead of manually re-declaring every @ai_function as a pass-through, this mixin delegates attribute lookups to the underlying tool instances. Kani discovers tools via dir(self) + getattr(self, name); by overriding both, all @ai_function methods on the composed tool objects are surfaced to the agent framework automatically.

class veupath_chatbot.ai.tools.strategy_registry.StrategyToolsMixin[source]

Bases: object

Mixin providing strategy, execution, result, and conversation @ai_function methods.

Classes using this mixin must set these attributes before Kani.__init__ runs (which is where tool discovery happens):

  • strategy_tools: StrategyTools

  • execution_tools: ExecutionTools

  • result_tools: ResultTools

  • conversation_tools: ConversationTools

strategy_tools: StrategyTools = None
execution_tools: ExecutionTools = None
result_tools: ResultTools = None
conversation_tools: ConversationTools = None

Execution Tools

Purpose: Tools for retrieving strategy execution results (e.g. result counts for built steps). Includes WDK error handling for common API failures.

Key class: ExecutionTools

Tools for retrieving strategy results.

class veupath_chatbot.ai.tools.execution_tools.ExecutionTools(session)[source]

Bases: ValidationMixin

Tools for retrieving strategy execution results.

async get_result_count(wdk_step_id, wdk_strategy_id=None)[source]

Get the result count for a built step.

For imported WDK strategies, provide wdk_strategy_id.

Return type:

JSONObject

Catalog Tools

Purpose: Catalog discovery tools: site listing, record types, search queries, parameter specs. Called by the agent to explore VEuPathDB data.

AI tool wrappers for catalog/discovery.

The underlying logic lives in veupath_chatbot.services.catalog to keep things DRY.

class veupath_chatbot.ai.tools.catalog_tools.CatalogTools[source]

Bases: object

Tools for exploring VEuPathDB catalog.

async list_sites()[source]
Return type:

JSONArray

async get_record_types(site_id)[source]
Return type:

JSONArray

async search_for_searches(site_id, query, keywords=None)[source]

Find WDK searches by description and/or keywords.

Returns a ranked list with name, displayName, description, category, and what the search returns (genes, SNPs, etc.).

The query is matched against display names and descriptions. Keywords are matched against the internal search name (urlSegment) with heavy boosting — use these when you know part of the search identifier.

Return type:

list[dict[str, str]]

async list_transforms(site_id, record_type)[source]

List available transform and combine operations (with descriptions).

Returns searches that chain onto a previous step’s results — such as ortholog transforms, weight filters, span logic, and boolean combines. Use this when you need to transform or combine step results. Always call this before attempting to use a transform search in create_step.

Return type:

list[dict[str, str]]

async list_searches(site_id, record_type)[source]

List all search names for a record type (names only, no descriptions).

Returns a lightweight index of search names. Use search_for_searches first for targeted discovery with descriptions. Use get_search_parameters to get full details (description + parameters) for a specific search.

Return type:

list[dict[str, str]]

async get_search_parameters(site_id, record_type, search_name)[source]

Get full details for a specific search: description, parameters, and valid values.

Return type:

JSONObject

async lookup_phyletic_codes(site_id, record_type, query)[source]

Look up phyletic species/group codes by name for GenesByOrthologPattern.

Returns {code, label, leaf} triples. Use codes in profile_pattern: %CODE:Y% (include) or %CODE:N% (exclude). Group codes (leaf=false) with :N are auto-expanded to all leaf descendants. Example: lookup ‘mammal’ → MAMM (leaf=false), use ‘%MAMM:N%pfal:Y%’.

Return type:

JSONObject

Catalog RAG Tools

Purpose: RAG-augmented catalog tools. Semantic search over the embedded VEuPathDB catalog for record types and searches.

AI tools for Qdrant-backed catalog retrieval.

Thin delegation layer — all logic lives in services.catalog.rag_search.

class veupath_chatbot.ai.tools.catalog_rag_tools.CatalogRagTools(*, site_id, disabled=False)[source]

Bases: object

RAG-first tools for exploring VEuPathDB catalog.

These tools read from Qdrant and fall back to authoritative WDK calls only for context-dependent vocab (dependent params) via the cached pathway.

When disabled=True all methods return empty results, allowing RAG ablation experiments without removing tool registrations.

__init__(*, site_id, disabled=False)[source]
async rag_get_record_types(query=None, limit=20, min_score=0.4)[source]
Return type:

JSONArray

async rag_get_record_type_details(record_type_id)[source]
Return type:

JSONObject | None

async rag_search_for_searches(query, record_type=None, limit=20, min_score=0.4)[source]
Return type:

JSONArray

async rag_get_search_metadata(record_type, search_name)[source]
Return type:

JSONObject | None

async rag_get_dependent_vocab(record_type, search_name, param_name, context_values=None)[source]
Return type:

JSONObject

Example Plans RAG Tools

Purpose: RAG retrieval of example strategy plans. Helps the agent suggest plan structures based on similar prior plans.

AI tools for retrieving example plans from Qdrant.

Thin delegation layer — all logic lives in services.catalog.rag_search.

class veupath_chatbot.ai.tools.example_plans_rag_tools.ExamplePlansRagTools(*, site_id, disabled=False)[source]

Bases: object

RAG tools for example plan retrieval.

When disabled=True all methods return empty results for ablation.

__init__(*, site_id, disabled=False)[source]
async rag_search_example_plans(query, limit=5)[source]
Return type:

JSONArray

Conversation Tools

Purpose: Conversation management tools: save/load strategy, update name, session control. Used by the agent to manage the user’s session.

Tools for conversation and strategy management.

class veupath_chatbot.ai.tools.conversation_tools.ConversationTools(session, user_id=None)[source]

Bases: object

Tools for managing conversations and saved strategies.

__init__(session, user_id=None)[source]
async save_strategy(name, description=None, graph_id=None)[source]

Save the current strategy for later use.

The strategy will be saved to the user’s account and can be loaded again in future conversations.

Return type:

JSONObject

async rename_strategy(new_name, description, graph_id=None)[source]

Rename the current strategy.

Return type:

JSONObject

async clear_strategy(graph_id=None, confirm=False)[source]

Clear the current strategy and start fresh.

This removes all steps and the current strategy. Requires explicit confirmation.

Return type:

JSONObject

async get_strategy_summary(graph_id=None)[source]

Get a summary of the current strategy.

Returns step count, record type, and other metadata.

Return type:

JSONObject

Query Validation

Purpose: Validate tool arguments and queries before execution. Catch malformed inputs before they reach WDK.

veupath_chatbot.ai.tools.query_validation.tokenize_query(text)[source]
Return type:

list[str]

veupath_chatbot.ai.tools.query_validation.record_type_query_error(query)[source]

Return a validation error object if the query is too vague; otherwise None.

Parameters:

query (str) – User query string.

Returns:

Error dict if query is too vague, otherwise None.

Return type:

JSONObject | None

veupath_chatbot.ai.tools.query_validation.search_query_error(query, *, has_keywords=False)[source]

Return a validation error object if the query is invalid; otherwise None.

When has_keywords is True, short/vague queries are allowed because the keywords provide the specificity.

Parameters:

  • query (str) – User query string.

  • has_keywords (bool) – Whether the caller also provided keyword hints.

Returns:

Error dict if query is invalid or too vague, otherwise None.

Return type:

JSONObject | None

Agent Tool Submodules

Individual tool modules for artifact management, gene lookup, optimization, and experiment tools. These are mixed into the unified agent via UnifiedToolRegistryMixin.

Tools for planning artifacts, conversation titles, and reasoning.

Provides ArtifactToolsMixin with tools for saving planning artifacts, setting conversation titles, and reporting reasoning.

class veupath_chatbot.ai.tools.planner.artifact_tools.ArtifactToolsMixin[source]

Bases: object

Kani tool mixin for planning artifact management.

async save_planning_artifact(title, summary_markdown, assumptions=None, parameters=None, proposed_strategy_plan=None)[source]

Publish a reusable planning artifact (persisted to the conversation).

Return type:

JSONObject

async set_conversation_title(title)[source]

Update the conversation title.

Return type:

JSONObject

async report_reasoning(reasoning)[source]

Publish reasoning text to the Thinking tab.

Return type:

JSONObject

Planner-mode tools for running control tests.

Provides ExperimentToolsMixin with the run_control_tests tool.

class veupath_chatbot.ai.tools.planner.experiment_tools.ExperimentToolsMixin[source]

Bases: object

Kani tool mixin for experiment control tests.

site_id: str = ''
async run_control_tests(record_type, target_search_name=None, target_parameters=None, wdk_step_id=None, controls_search_name='GeneByLocusTag', controls_param_name='ds_gene_ids', positive_controls=None, negative_controls=None, controls_value_format='newline', controls_extra_parameters=None, id_field=None)[source]

Run control tests against a WDK search OR a built strategy step.

Two modes: (1) Standalone search — provide target_search_name + target_parameters; creates a temporary WDK strategy to intersect. (2) Built step — provide wdk_step_id from list_current_steps; tests directly against the strategy’s actual results (recommended after building a multi-step strategy).

Return type:

JSONObject

Planner-mode tools for gene record lookup and resolution.

Provides GeneToolsMixin with tools for searching and resolving gene records via VEuPathDB site-search.

class veupath_chatbot.ai.tools.planner.gene_tools.GeneToolsMixin[source]

Bases: object

Kani tool mixin for gene record lookup.

site_id: str = ''
async lookup_gene_records(query, organism=None, limit=10)[source]

Look up gene records by name, symbol, or description using VEuPathDB site-search.

Use this to resolve human-readable gene names (from literature or user input) to VEuPathDB gene IDs. The returned IDs can then be used as positive/negative controls in run_control_tests or optimize_search_parameters.

Return type:

JSONObject

async resolve_gene_ids_to_records(gene_ids, record_type='transcript', search_name='GeneByLocusTag', param_name='ds_gene_ids')[source]

Resolve known gene IDs to full records (product name, organism, gene type).

Use this to validate gene IDs or fetch metadata for IDs you already have (e.g. from literature). For discovering genes by name, use lookup_gene_records instead.

Return type:

JSONObject

Planner-mode tool for search parameter optimization.

Provides OptimizationToolsMixin with the long-running optimize_search_parameters tool.

class veupath_chatbot.ai.tools.planner.optimization_tools.OptimizationToolsMixin[source]

Bases: object

Kani tool mixin for search parameter optimization.

site_id: str = ''
async optimize_search_parameters(record_type, search_name, parameter_space_json, fixed_parameters_json, controls_search_name, controls_param_name, positive_controls=None, negative_controls=None, budget=15, objective='f1', beta=1.0, method='bayesian', controls_value_format='newline', controls_extra_parameters_json=None, id_field=None, result_count_penalty=0.1)[source]

Optimise search parameters against positive/negative control gene lists.

Runs multiple trials, varying the parameters in parameter_space while holding fixed_parameters constant. Each trial evaluates the search against the controls and scores the result. Returns the best configuration, all trials, Pareto frontier, and sensitivity analysis.

This is a long-running operation. The user will see real-time progress in the UI. Always confirm the plan with the user before calling this.

Return type:

str

Strategy Tool Submodules

Individual strategy tool modules for step creation, graph building, attachment operations, discovery, and editing.

Step creation tools (AI-exposed).

class veupath_chatbot.ai.tools.strategy_tools.step_ops.StrategyStepOps(session)[source]

Bases: StrategyToolsHelpers

Tools that add new steps to a graph.

async create_step(search_name=None, parameters=None, record_type=None, primary_input_step_id=None, secondary_input_step_id=None, operator=None, display_name=None, upstream=None, downstream=None, strand=None, graph_id=None)[source]

Create a new strategy step.

Step kind is inferred from structure: - leaf step: no inputs - unary step: primary_input_step_id only - binary step: primary + secondary input (+ operator)

Return type:

JSONObject

Graph inspection tools (AI-exposed).

class veupath_chatbot.ai.tools.strategy_tools.graph_ops.CreateStepProtocol(*args, **kwargs)[source]

Bases: Protocol

Protocol for classes that have a create_step method.

async create_step(search_name=None, parameters=None, record_type=None, primary_input_step_id=None, secondary_input_step_id=None, operator=None, display_name=None, upstream=None, downstream=None, strand=None, graph_id=None)[source]

Create a step in the graph.

Return type:

JSONObject

__init__(*args, **kwargs)
class veupath_chatbot.ai.tools.strategy_tools.graph_ops.StrategyGraphOps(session)[source]

Bases: StrategyToolsHelpers

Graph inspection tools.

async list_current_steps(graph_id=None)[source]

List all steps in the current strategy graph.

Returns graph metadata and per-step details including WDK step IDs and estimated result counts (when the strategy has been built).

Return type:

JSONObject

async validate_graph_structure(graph_id=None)[source]

Validate that the working graph is structurally sound and has one output.

This is a “done check” tool for the orchestrator. It verifies the single-output invariant (exactly one root) and detects broken references.

Return type:

JSONObject

async ensure_single_output(graph_id=None, operator='INTERSECT', display_name=None)[source]

Ensure the graph has exactly one output by combining orphan roots.

If multiple roots exist, chains combines until one root remains. Default operator is INTERSECT (most strategies are filter chains).

Return type:

JSONObject

Editing tools for existing graph steps (AI-exposed).

class veupath_chatbot.ai.tools.strategy_tools.edit_ops.StrategyEditOps(session)[source]

Bases: StrategyToolsHelpers

Tools that mutate existing steps/graph state.

async delete_step(step_id, graph_id=None)[source]

Delete a step from the graph (and dependent steps).

Return type:

JSONObject

async undo_last_change(graph_id=None)[source]

Undo the last change to the strategy.

Return type:

JSONObject

async rename_step(step_id, new_name, graph_id=None)[source]

Rename a step with a new display name.

Return type:

JSONObject

async update_step(step_id, search_name=None, parameters=None, operator=None, display_name=None, graph_id=None)[source]

Update an existing strategy step’s search, parameters, operator, or display name.

Return type:

JSONObject

Discovery/search helper tools (AI-exposed).

class veupath_chatbot.ai.tools.strategy_tools.discovery_ops.StrategyDiscoveryOps(session)[source]

Bases: StrategyToolsHelpers

Discovery/search tools.

async search_searches_by_keywords(keywords, record_type=None, limit=20)[source]

Search available questions by keywords across name/display/description.

Return type:

JSONObject

async explain_operator(operator)[source]

Explain what a combine operator does.

Return type:

str

Tools for attaching filters/analyses/reports to steps (AI-exposed).

class veupath_chatbot.ai.tools.strategy_tools.attachment_ops.StrategyAttachmentOps(session)[source]

Bases: StrategyToolsHelpers

Tools that attach metadata/configuration to existing steps.

async add_step_filter(step_id, filter_name, value, disabled=False, graph_id=None)[source]

Attach or update a filter on a step.

Return type:

JSONObject

async add_step_analysis(step_id, analysis_type, parameters=None, custom_name=None, graph_id=None)[source]

Attach an analysis configuration to a step.

Return type:

JSONObject

async add_step_report(step_id, report_name='standard', config=None, graph_id=None)[source]

Attach a report configuration to a step.

Return type:

JSONObject

Public AI tool operations for strategy building.

This module composes the public StrategyTools class from smaller, purpose-driven mixins to keep tool implementations easier to navigate.

class veupath_chatbot.ai.tools.strategy_tools.operations.StrategyTools(session)[source]

Bases: StrategyGraphOps, StrategyDiscoveryOps, StrategyStepOps, StrategyEditOps, StrategyAttachmentOps

Tools for building search strategies.

This class uses multiple inheritance to compose tool methods from mixins. StrategyStepOps provides create_step, which StrategyGraphOps.ensure_single_output uses.

__init__(session)[source]

Initialize StrategyTools with a session.

Export Tools

Purpose: Data export tools for strategies, gene sets, and experiment results.

AI tools for exporting data as downloadable files.

class veupath_chatbot.ai.tools.export_tools.ExportToolsMixin[source]

Bases: object

Kani tool mixin for exporting data as downloadable files.

site_id: str = ''
user_id: UUID | None = None
async export_gene_set(gene_set_id, format='csv')[source]

Export a gene set as a downloadable CSV or TXT file.

Returns a download URL that the user can click to download the file. The URL expires after 10 minutes.

Return type:

JSONObject

Workbench Tools

Purpose: Workbench data access and analysis tools.

Read-only AI tools for workbench experiment data access.

Provides function-calling tools that let the workbench AI agent read experiment results: evaluation summary, enrichment, confidence scores, step contributions, config, ensemble analysis, and gene lists by classification category.

All tools follow the thin @ai_function wrapper pattern: fetch experiment from store, return structured JSON, return {“error”: …} when data is absent.

class veupath_chatbot.ai.tools.workbench_read_tools.WorkbenchReadToolsMixin[source]

Bases: object

Mixin providing read-only @ai_function methods for workbench experiment data.

Classes using this mixin must provide: - site_id: str - experiment_id: str - _get_experiment() -> Experiment | None (async)

site_id: str = ''
experiment_id: str = ''
async get_evaluation_summary()[source]

Get a summary of the experiment evaluation results.

Returns classification metrics, confusion matrix counts, and sample gene IDs from each classification category (TP/FP/FN/TN).

Return type:

JSONObject

async get_enrichment_results()[source]

Get the enrichment analysis results for this experiment.

Returns GO term, pathway, and word enrichment results. Each result includes the analysis type, enriched terms with p-values, and background statistics.

Return type:

JSONObject

async get_confidence_scores()[source]

Get cross-validation confidence scores for this experiment.

Returns mean metrics, per-fold metrics, standard deviations, and overfitting assessment. Indicates how robustly the strategy generalises.

Return type:

JSONObject

async get_step_contributions()[source]

Get the step contribution (ablation) analysis for this experiment.

Returns per-step recall delta, FPR delta, and verdict indicating whether each search step adds meaningful value to the strategy.

Return type:

JSONObject

async get_experiment_config()[source]

Get the experiment configuration, status, and WDK strategy IDs.

Returns the full config (search name, parameters, controls, mode), current execution status, and WDK strategy/step IDs if available.

Return type:

JSONObject

async get_ensemble_analysis()[source]

Get the full ensemble step analysis for this experiment.

Returns step evaluations, operator comparisons, step contributions, and parameter sensitivities. Useful for understanding multi-step strategy behaviour in detail.

Return type:

JSONObject

async get_result_gene_lists(classification, limit=50)[source]

Get gene IDs for a specific classification category.

Returns gene IDs and basic metadata (name, organism, product) for the requested category. Use ‘tp’ for hits that are known positives, ‘fp’ for hits that are known negatives, ‘fn’ for missed known positives, ‘tn’ for non-hits that are known negatives.

Return type:

JSONObject

AI tools for workbench gene set operations.

class veupath_chatbot.ai.tools.planner.workbench_tools.WorkbenchToolsMixin[source]

Bases: object

Kani tool mixin for workbench gene set operations.

site_id: str = ''
user_id: UUID | None = None
async create_workbench_gene_set(name, gene_ids, search_name=None, record_type='transcript', parameters=None, wdk_strategy_id=None, wdk_step_id=None)[source]

Create a gene set in the user’s Workbench for further analysis.

Use this tool after building a strategy or collecting gene IDs to send them to the Workbench where the user can run enrichment analysis, evaluate strategies, compare gene sets, and more.

The created gene set will appear in the user’s Workbench sidebar.

Return type:

JSONObject

async run_gene_set_enrichment(gene_set_id, enrichment_types=None)[source]

Run enrichment analysis on a gene set in the Workbench.

This performs over-representation analysis (ORA) to find enriched GO terms, pathways, or word patterns in the gene set. Requires the gene set to have a WDK step ID or search parameters.

Return type:

JSONObject

async list_workbench_gene_sets()[source]

List all gene sets currently in the user’s Workbench.

Returns a summary of each gene set including name, gene count, source, and ID. Use this to check what’s available before running analyses.

Return type:

JSONObject

WDK Error Handler

Purpose: Error handling and formatting for WDK API errors during tool execution.

Shared WDK step error handling for result-fetching tools.

veupath_chatbot.ai.tools.wdk_error_handler.handle_wdk_step_error(e, *, wdk_step_id, action, fallback_message)[source]
Return type:

JSONObject

Combined Result

Purpose: Combine and merge results from multiple tool sources.

Shared helper for building combined RAG + WDK tool outputs.

veupath_chatbot.ai.tools.combined_result.combined_result(*, rag, wdk, rag_note=None, wdk_note=None)[source]

Standardize combined (RAG + WDK) tool outputs.

Callers always receive both data sources and can decide which to trust based on availability/staleness.

Parameters:

  • rag (JSONValue) – RAG context.

  • wdk (JSONValue) – WDK context.

  • rag_note (str | None) – RAG note (default: None).

  • wdk_note (str | None) – WDK note (default: None).

Return type:

JSONObject

Catalog Registry

Purpose: Catalog tool registry mixin.

Catalog tool methods (RAG + WDK combined lookups).

class veupath_chatbot.ai.tools.catalog_registry.CatalogToolsMixin[source]

Bases: object

Mixin providing catalog @ai_function methods.

Classes using this mixin must provide: - site_id: str - catalog_tools: CatalogTools - catalog_rag_tools: CatalogRagTools - example_plans_rag_tools: ExamplePlansRagTools

site_id: str = ''
catalog_tools: CatalogTools = None
catalog_rag_tools: CatalogRagTools = None
example_plans_rag_tools: ExamplePlansRagTools = None
async list_sites()[source]

List all available VEuPathDB sites.

Return type:

JSONObject

async get_record_types(query=None, limit=20)[source]

Get available record types for the current site (returns both RAG and live WDK).

Return type:

JSONObject

async get_record_type_details(record_type_id)[source]

Get full record-type details from RAG (Qdrant payload).

Return type:

JSONObject

async list_searches(record_type)[source]

List available searches for a record type on the current site (returns both RAG and live WDK).

Return type:

JSONObject

async get_search_parameters(record_type, search_name)[source]

Get detailed parameter info for a search (returns both RAG and live WDK).

Return type:

JSONObject

async search_for_searches(query, keywords=None, record_type=None, limit=20)[source]

Find WDK searches by description and/or keywords — returns a single ranked list.

Results include name, displayName, description, category (e.g. percentile, fold_change), and what record type the search returns (genes, SNPs, etc.). Chooser/routing searches (zero-param menu entries) are automatically filtered out.

Return type:

list[dict[str, str]]

async lookup_phyletic_codes(query, record_type='transcript')[source]

Look up phyletic species/group codes by name for GenesByOrthologPattern.

Returns {code, label, leaf} triples. Use codes in profile_pattern: %CODE:Y% (include) or %CODE:N% (exclude). Group codes (leaf=false) with :N are auto-expanded to all leaf descendants. Example: lookup ‘mammal’ -> MAMM (leaf=false), use ‘%MAMM:N%pfal:Y%’.

Return type:

JSONObject

async get_dependent_vocab(record_type, search_name, param_name, context_values=None)[source]

Get dependent vocab for a parameter.

Note

WDK’s /refreshed-dependent-params requires a changed param value; if context_values does not include param_name, we cannot call that endpoint safely (it will 422 for many params). In that case we fall back to fetching expanded search details and returning the parameter spec (which often includes the vocabulary needed to pick an initial value).

Return type:

JSONObject

async search_example_plans(query, limit=5)[source]

Retrieve relevant public example plans (returns both RAG and live WDK availability note).

Return type:

JSONObject