🛠️ beamcore/tools

This is a highly optimized, lightweight (270M parameters) function-calling model fine-tuned on top of google/functiongemma-270m-it. It is specifically designed to run on-device (locally) as a pre-flight search and routing assistant for the Elixir-native Beamcore agent harness.

🚀 Purpose & Workflow

In agentic software engineering workflows, sending large workspace structures, complete file contents, and extensive tool schemas to massive frontier models is slow, expensive, and leads to context pollution.

beamcore/tools solves this by running locally to perform pre-flight search routing:

1. Analyze Intent: When a user issues a request, beamcore/tools determines whether search/traversal tools are needed to gather codebase context.
2. Execute Tools: If context is missing, it emits structured tool calls (e.g., glob, grep, tree, read) to fetch local file structures or code.
3. Minimize Tokens: If no tools are required (or after search tools run and collect the necessary files), the main reasoning model is invoked with a minimal, relevant context, drastically reducing token overhead and billing.

graph TD
    User([User Request]) --> Helper[beamcore/tools (Local 270M)]
    Helper -->|Needs Context?| ToolCall{Tool Call?}
    ToolCall -->|Yes| Exec[Execute Local Tool]
    Exec --> Read[Read/Grep/Glob Result]
    Read --> Main[Main Beamcore Agent]
    ToolCall -->|No / Finished| Main

🛠️ Supported Tools

The model is fine-tuned to work with the following four workspace-inspection tools:

1. glob

Find workspace files matching a glob pattern relative to a path.

• Parameters: pattern (string, required), path (string, optional), all (boolean, optional).
• Example: {"pattern": "**/*.ex"}

2. grep

Search workspace file contents by regex with optional includes.

• Parameters: pattern (string, required), path (string, optional), include (string, optional), all (boolean, optional).
• Example: {"pattern": "defmodule", "include": "*.ex"}

3. tree

Show a compact workspace directory tree with sizes.

• Parameters: path (string, optional).
• Example: {"path": "lib/"}

4. read

Read a workspace-relative file or directory with offset/limit parameters.

• Parameters: filePath (string, required), offset (integer, optional), limit (integer, optional).
• Example: {"filePath": "lib/beamcore.ex", "limit": 100}

---

💻 Quickstart (Inference)

You can run beamcore/tools locally using transformers:

import json
from transformers import AutoTokenizer, AutoModelForCausalLM
from transformers.utils import get_json_schema

# Define tool signatures (converted to JSON Schema)
def glob(pattern: str, path: str = None, all: bool = False): pass
def grep(pattern: str, path: str = None, include: str = None, all: bool = False): pass
def tree(path: str = None): pass
def read(filePath: str, offset: int = 1, limit: int = 200): pass

tools = [
    get_json_schema(glob),
    get_json_schema(grep),
    get_json_schema(tree),
    get_json_schema(read)
]

# Load model and tokenizer
model_id = "beamcore/tools"
model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")
tokenizer = AutoTokenizer.from_pretrained(model_id)

# System prompt
system_msg = "You are a pre-flight search assistant for a coding agent. Your ONLY job is to analyze the user request and determine if search or directory traversal tools are needed to find relevant code or files before the main coding agent answers."

messages = [
    {"role": "developer", "content": system_msg},
    {"role": "user", "content": "Find all Elixir source files in the project lib/ directory"}
]

# Format chat using tools
inputs = tokenizer.apply_chat_template(messages, tools=tools, return_tensors="pt").to(model.device)
outputs = model.generate(inputs, max_new_tokens=256)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

📈 Training Details

• Base Model: google/functiongemma-270m-it
• Training Method: Supervised Fine-Tuning (SFT) using TRL
• Dataset: Custom search routing examples representing diverse developer queries (directory tree traversal, pattern matching, file reads, and conversational non-search queries).

Framework Versions

• TRL: 1.5.1
• Transformers: 5.10.2
• Pytorch: 2.12.0
• Datasets: 5.0.0
• Tokenizers: 0.22.2