tools/README.md

---
base_model: google/functiongemma-270m-it
library_name: transformers
model_name: beamcore/tools
tags:
- agent
- tool-use
- function-calling
- on-device
- beamcore
- sft
- trl
license: gemma
---

# 🛠️ 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](https://beamcore.dev).

## 🚀 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.

```mermaid
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`:

```python
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