Add a tool

What ships today

지금 들어 있는 것

Tool도구	Source출처
`get_weather`, `get_weather_forecast`	Open-Meteo
`get_calendar_events`, `get_upcoming_holidays`	Nager.Date
`get_exchange_rate`	exchangerate-api.com
`calculate`	Local로컬
`search_web`, `search_website`, `fetch_webpage`	SerpApi, Bing fallbackSerpApi, Bing 대체

1. Write the test first

1. 테스트를 먼저

Gemstone is developed test-first. Start with a test in api/tests/ that calls your function and fails because it does not exist yet. Run it with uv run --extra torch pytest.

Gemstone 은 테스트 우선으로 개발합니다. api/tests/ 에 아직 없는 함수를 불러서 실패하는 테스트부터 씁니다. uv run --extra torch pytest 로 실행합니다.

2. Implement the function

2. 함수 구현

Add a module under api/src/main/utils/. Take JSON-friendly arguments and return a string the model can read:

api/src/main/utils/ 아래에 모듈을 추가합니다. JSON 으로 표현 가능한 인자를 받고, 모델이 읽을 문자열을 돌려줍니다:

# api/src/main/utils/clock.py
from datetime import datetime
from zoneinfo import ZoneInfo

def get_time(timezone: str) -> str:
    return datetime.now(ZoneInfo(timezone)).isoformat()

3. Register it

3. 등록

In api/src/main/utils/__init__.py, import the module, add a FunctionSchema to FunctionCalling.DEFAULT.schemas and the function to implementations:

api/src/main/utils/__init__.py 에서 모듈을 import 하고, FunctionCalling.DEFAULT.schemas 에 FunctionSchema 를, implementations 에 함수를 추가합니다:

FunctionSchema(
    name="get_time",
    description="Get the current time in an IANA timezone",
    parameters={
        "type": "object",
        "properties": {"timezone": {"type": "string", "description": "e.g. Asia/Seoul"}},
        "required": ["timezone"],
    },
),
...
implementations=dict(..., get_time=clock.get_time)

How it runs

어떻게 실행되나

When the model emits a tool call, the server runs the function on a thread pool, so several calls proceed in parallel. An exception becomes the tool's result text rather than an error. The result goes into the history and the model generates again. Models with tools disabled (none today) never see the schema.

모델이 도구 호출을 내보내면 서버가 스레드 풀에서 함수를 실행하므로 여러 호출이 병렬로 진행됩니다. 예외는 오류가 아니라 도구의 결과 텍스트가 됩니다. 결과는 기록에 들어가고 모델이 다시 생성합니다. 도구가 꺼진 모델(지금은 없음)은 스키마를 보지 못합니다.

A tool that calls the internet sends the user's words to a third party. Gemstone's intent is privacy-first; prefer local tools, and say so in your pull request when you cannot.

인터넷을 부르는 도구는 사용자의 말을 제3자에게 보냅니다. Gemstone 의 의도는 프라이버시 우선입니다. 로컬 도구를 우선하고, 그럴 수 없다면 풀 리퀘스트에 그렇게 적어 주세요.

도구 추가