Top-Level Modules

Standalone modules at the oats package root.

oats.date

Date/time utilities for oats.

oats.date.utc()

get the utc datetime

Return type:

datetime

oats.date.naive()

get naive datetime from utc

# Timezone Aware UTC

print(datetime.now(timezone.utc)) 2025-10-05 15:11:31.981400+00:00

# Return as Timezone Naive Datetime

print(datetime.now(timezone.utc).replace(tzinfo=None)) 2025-10-05 15:13:54.423262

Return type:

datetime

oats.date.get_third_friday_dates()

Generate a list of the third Friday dates for the next 6 months. Returns dates in YYYYMMDD format, space-delimited.

oats.date.get_utc_str()

get the utc datetime

Return type:

str

oats.log

Logging utilities for oats.

class oats.log.Lg(name='lg', colors_enabled=None, file=None)

Bases: object

A very basic logger that prints to stdout. Designed for easy monkey-patching and debugging.

disable colors with export COLORS_ENABLED=0 colors are enabled by default.

__init__(name='lg', colors_enabled=None, file=None)

Initialize the logger with the given name and options.

log(level, m)

Logs a message with a given level.

Return type:

None

debug(m)

Log a debug-level message.

Return type:

None

info(m)

Log an info-level message.

Return type:

None

warn(m)

Log a warning-level message.

Return type:

None

warning(m)

Log a warning-level message.

Return type:

None

err(m)

Log an error-level message.

Return type:

None

error(m)

Log an error-level message.

Return type:

None

critical(m)

Log a critical-level message.

Return type:

None

good(m)

Log a success/good message.

Return type:

None

p(m)

Log a pass message.

Return type:

None

fail(m)

Log a failure message.

Return type:

None

startup(m)

Log a startup message.

Return type:

None

agent_log(m)

Log an agent-specific message.

Return type:

None

get_file()

Return the log file path, if set.

Return type:

str | None

save_all(file)

Save all accumulated logs to the configured file.

Return type:

None

save(file, num_logs=10, total_len=500, is_append=False)

Write the last num_logs entries to file (truncated to total_len chars).

Return type:

None

get_logs()

Return the list of accumulated log strings.

Return type:

list[str]

set_file(file)

Set the log file path.

Return type:

None

enable_logs()

Enable log output to console.

Return type:

None

oats.log.create_log(n='lg', colors=True, file=None)

Creates a logger Lg instance.

Parameters:

• name – The name of the logger (for identification in logs).

• colors – enable colors in the log

• file – enable saving the logs to this file

Returns:

A Lg instance.

oats.log.cl(n='lg', colors=True, file=None)

Creates a logger Lg instance.

Parameters:

• name – The name of the logger (for identification in logs).

• colors – enable colors in the log

• file – enable saving the logs to this file

Returns:

A Lg instance.

oats.log.gl(n=None, colors=None, file=None)

Initializes a global logger Lg instance - disabled by default

Parameters:

• name – The name of the logger (for identification in logs).

• colors – enable colors in the log

• file – enable saving the logs to this file

Returns:

A Lg instance.

oats.models

Data models for the OAT (Open Agent Tools) system.

class oats.models.OatPromptChoices(**data)

Bases: BaseModel

Container for tool-choice results returned by the OAT index.

status: bool

actions: list[str]

prompts: list[str]

src_files: list[str]

partial_actions: list[str]

partial_prompts: list[str]

partial_src_files: list[str]

index_files: list[str]

tool_data: dict

version: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class oats.models.OatConfig(*, repo_uses_index: str = './.ai/AGENT.repo_uses.python.tools.json', repo_uses_data: dict = {}, repo_uses_actions: list = [], repo_uses_prompts: list = [], repo_uses_src_files: list = [], repo_uses_action_to_src_dict: dict = {}, repo_uses_prompt_dict: dict = {}, best_tools: list[dict] = [], best_impls: dict = {})

Bases: BaseModel

Configuration and index data for OAT tool resolution.

repo_uses_index: str

repo_uses_actions: list

repo_uses_prompts: list

repo_uses_src_files: list

repo_uses_action_to_src_dict: dict

repo_uses_prompt_dict: dict

__init__(**kwargs)

Load the OAT index file and build action/prompt lookup dictionaries.

best_tools: list[dict]

best_impls: dict

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

repo_uses_data: dict

get_prompt_choices(prompt, verbose=False)

Find tool matches for a prompt using exact and partial string matching.

Return type:

OatPromptChoices

get_best_matches_bm25(prompt, top_k=5, verbose=False)

Use BM25 to find the best matching actions for a given prompt.

Compares the prompt against each key in repo_uses_action_to_src_dict and returns the top_k best matches sorted by BM25 score.

Return type:

OatPromptChoices

oats.pp

Pretty-printing utilities for structured data.

oats.pp.pp(d=None)

Pretty-print a data structure to a JSON string.

Return type:

str

oats.get_oat_config

Lazy singleton loader for the OAT (Open Agent Tools) configuration.

oats.get_oat_config.get_oat_config()

Return the process-wide OatConfig singleton, creating it on first call.

Return type:

OatConfig

oats.setup_coder_config

Interactive CLI to generate a coder.json config file.

Prompts the user for vllm-small and t1 provider settings, then writes a new config file (default: /tmp/coder.json).

Usage:

python setup_coder_config.py -o /path/to/output.json python setup_coder_config.py # writes to /tmp/coder.json by default

oats.setup_coder_config.prompt(msg, default=None)

Prompt the user with an optional default value.

Return type:

str

oats.setup_coder_config.ensure_v1_suffix(url)

Append /v1 to the base_url if it’s missing.

Return type:

str

oats.setup_coder_config.collect_vllm_small()

Collect vllm-small provider configuration from the user.

Return type:

dict

oats.setup_coder_config.collect_t1()

Collect t1 provider (tool-calling) configuration from the user.

Return type:

dict

oats.setup_coder_config.main()

CLI entry point: interactively generate a coder.json config file.

oats.agent_get_tool_choices_for_prompt

Get tool choices for a user prompt from the OAT index.

Tries exact-match lookup first, then falls back to BM25 ranking.

oats.agent_get_tool_choices_for_prompt.agent_get_tool_choices_for_prompt(prompt, top_k=5, verbose=False)

Get the best tool choices for a prompt, trying exact match then BM25.

Return type:

OatPromptChoices

oats.agent_get_tool_choices_for_prompt.parse_args(args=None)

Parse CLI arguments for the tool-choices CLI.

Return type:

Namespace

oats.agent_get_tool_choices_for_prompt.main(args=None)

CLI entry point: look up tool choices and print JSON.

oats.call_tool_with_loader1

Call tool with loader — dynamically load tools from source and wrap them as LocalTool instances.

class oats.call_tool_with_loader1.LocalTool

Bases: Tool

A Tool whose attributes are set via setters rather than hard-coded properties.

__init__()

set_name(value)

Return type:

None

set_aliases(value)

Return type:

None

set_keywords(value)

Return type:

None

set_always_load(value)

Return type:

None

set_strict(value)

Return type:

None

set_description(value)

Return type:

None

set_parameters(value)

Return type:

None

set_requires_permission(value)

Return type:

None

set_output(value)

Return type:

None

set_tool_context(value)

Return type:

None

set_impl(impl)

Return type:

None

property name: str

Unique identifier for the tool.

property description: str

Description of what the tool does.

property parameters: dict[str, Any]

JSON Schema for the tool parameters.

property aliases: list[str]

Optional alternate names for backwards compatibility.

property keywords: list[str]

Short search terms describing when this tool should be used.

property always_load: bool

Whether this tool should almost always be available to the model.

Mirrors Claude Code’s “alwaysLoad” concept in a lightweight way so essential tools stay visible even when we rank the broader tool set.

property strict: bool

Whether provider-side tool schema adherence should be as strict as the serving stack supports.

property output: str

requires_permission(args, ctx)

Check if this execution requires user permission.

Returns None if no permission needed, or a description of what permission is needed.

Return type:

str | None

async execute(args, ctx)

Execute the underlying callable and return a ToolResult.

Return type:

ToolResult

oats.call_tool_with_loader1.load_tools_from_repo_uses_index(prompt, file_path=None, min_score=0.0, verbose=False)

Import source code using get_best_tools_for_prompt(), then create a LocalTool for each matched tool.

Return type:

Tuple[bool, list, dict, list, list[dict], dict, list, list]

Parameters:

• file_path – Path to the tool-uses index JSON file (or None for default).

• prompt – The prompt to match tools against.

Returns:

A list of LocalTool instances ready for use.

oats.call_tool_with_loader1.run_tool_call(prompt, tools, tool_impls, provider_id=None, api_base=None, api_key=None, model=None, verbose=False)

Run a two-turn tool-call loop via LiteLLM and return the final answer.

Return type:

Tuple[bool, str]

oats.call_tool_with_loader1.main()

CLI entry point: load tools from index, wrap as LocalTool, and demo execution.

oats.determine_best_tools1

Find best tool matches from a uses schema using BM25 + optional cross-encoder reranker.

1. Pipe schema from stdin (quickest) cat schema.json | python3 determine_tool_matches.py -p “get date”

2. Pass schema file with -s python3 determine_tool_matches.py -p “utc datetime” -s my_schema.json -k 5 -w 0.1

3. With reranker for higher precision python3 determine_tool_matches.py -p “get date” -s schema.json -m bm25 -r This runs BM25 first (fast), then the cross-encoder reranks the candidates for better semantic accuracy.

# Search all Coder Tools For the Best Match

` ./oats/determine_best_tools2.py -s ./.ai/AGENT.repo_uses.python.tools.json -p 'utc' `

oats.determine_best_tools1.load_schema(schema_path)

Load the tool-uses JSON schema from a file or stdin.

Return type:

dict[str, dict[str, str]]

oats.determine_best_tools1.build_corpus(uses)

Build one document per (file, function) pair combining path + name + description.

Return type:

tuple[list[str], list[dict[str, str]]]

oats.determine_best_tools1.tokenize(text)

Lowercase and split text into whitespace-delimited tokens.

Return type:

list[str]

oats.determine_best_tools1.rank_with_bm25(query, corpus, meta, top_k, min_score)

Rank corpus documents against a query using BM25 scoring.

Return type:

list[dict[str, Any]]

oats.determine_best_tools1.rank_with_tfidf(query, corpus, meta, top_k, min_score)

Rank corpus documents against a query using TF-IDF + cosine similarity.

Return type:

list[dict[str, Any]]

oats.determine_best_tools1.rank_with_embeddings(query, corpus, meta, top_k, min_score, model_name)

Rank corpus documents against a query using dense embeddings + cosine similarity.

Return type:

list[dict[str, Any]]

oats.determine_best_tools1.rerank(query, results, rerank_model)

Rerank candidate results using a cross-encoder model.

Return type:

list[dict[str, Any]]

oats.determine_best_tools1.deduplicated(items)

Return a list of unique items preserving first-seen order.

Return type:

list[str]

oats.determine_best_tools1.determine_best_tools(prompt, schema, model='bm25', top_k=5, min_score=0.0, rerank=False, rerank_model='cross-encoder/ms-marco-MiniLM-L-6-v2', log_level='INFO', verbose=False)

Determine the best tool matches for a given prompt.

Return type:

dict[str, Any]

Parameters:

• prompt – Search query (e.g. ‘get date’)

• schema – Path to JSON schema file with ‘uses’ dict

• model – Retrieval model: bm25 | tfidf | <sentence-transformer-model-name>

• top_k – Number of top results

• min_score – Minimum retrieval score threshold

• rerank – Whether to apply cross-encoder reranker after retrieval

• rerank_model – Cross-encoder model for reranking

• log_level – Log level

Returns:

query, model, reranked, best_files, best_uses, results

Return type:

dict with keys

oats.determine_best_tools1.main()

CLI entry point: rank tool matches and print JSON output.

Return type:

None

oats.load_tools_from_source1

Dynamically load tool functions from source files and invoke them via an LLM.

Provides utilities to: - Load public functions from .py files as OpenAI-compatible tool schemas - Auto-select the best tools for a prompt using BM25 / OAT index - Run tool-call loops with a LiteLLM-compatible model

class oats.load_tools_from_source1.OatRepoUses(**data)

Bases: BaseModel

Container for OAT repo-level tool schema, prompts, and source file paths.

repo_uses_tool_schema_file: str

repo_uses_prompts: dict

repo_uses_tool_schema: dict

repo_src_files: list

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

oats.load_tools_from_source1.load_tools(file_paths, verbose=False)

Load public functions from each .py file. Returns (TOOLS list of OpenAI schemas, TOOL_IMPLS name→callable dict).

Return type:

tuple[list, dict]

oats.load_tools_from_source1.run_tool_call(model, api_base, prompt, tools, tool_impls)

Run a two-turn tool-call loop: LLM picks tools, we execute, LLM gives final answer.

Return type:

Tuple[bool, str, list[dict]]

oats.load_tools_from_source1.get_oat_repo_uses_tools()

Load and return the OAT repo tool schema, prompts, and source files.

Return type:

OatRepoUses

oats.load_tools_from_source1.get_best_tools_for_prompt(prompt, tool_schema=None, top_k=3, min_score=0.0, rerank=False, rerank_model='cross-encoder/ms-marco-MiniLM-L-6-v2', bm25_model='bm25', run=True, oat_enabled=True, verbose=False)

Examine the prompt, determine the best tool files via determine_best_tools(), then load only those files and run the tool call.

Return type:

Tuple[bool, list, dict, list, list, dict]

Parameters:

• prompt – The user prompt.

• tool_schema – Path to the JSON tool-uses index file.

• top_k – Number of top candidate files to consider.

• min_score – Minimum BM25/retrieval score threshold.

• rerank – Whether to apply cross-encoder reranking.

• rerank_model – Cross-encoder model name for reranking.

• bm25_model – Retrieval model name (bm25, tfidf, or embedding model).

oats.load_tools_from_source1.run_tool_for_prompt(prompt, model=None, api_base=None, schema=None, top_k=5, min_score=0.0, rerank=False, rerank_model='cross-encoder/ms-marco-MiniLM-L-6-v2', bm25_model='bm25', run=True)

Examine the prompt, determine the best tool files via determine_best_tools(), then load only those files and run the tool call.

Return type:

Tuple[bool, bool, list, dict, str, list[dict]]

Parameters:

• model – The model identifier for litellm.

• api_base – The API base URL.

• prompt – The user prompt.

• schema – Path to the JSON tool-uses index file.

• top_k – Number of top candidate files to consider.

• min_score – Minimum BM25/retrieval score threshold.

• rerank – Whether to apply cross-encoder reranking.

• rerank_model – Cross-encoder model name for reranking.

• bm25_model – Retrieval model name (bm25, tfidf, or embedding model).

• run – if False, skips running tool

oats.load_tools_from_source1.main()

CLI entry point for the dynamic tool loader.