How Twiga Works

Adding a Tool

Tools are how the model does things it cannot do by writing text. Adding one is mostly registration.

Twiga ships with five:

Tool	What it does
`search_knowledge`	Retrieves passages from the teacher's textbooks.
`create_lesson_plan`	Builds a structured lesson plan.
`generate_exercise`	Produces practice questions.
`solve_equation`	Works through mathematics, on its own model configuration.
`generate_necta_style_exam`	Produces an exam in the national format, delivered as a PDF.

The steps

Write the function
Create app/tools/tool_code/your_tool/main.py with an __init__.py beside it. Export one async function named after the tool. Return a string, which is what the model sees as the result.
Register the name
Add a member to the ToolName enum in app/tools/registry.py. The member name and its string value must match.
Map the name to the function
Import your function and add it to TOOL_FUNCTION_MAP in the same file.
Describe it to the model
Append a JSON schema entry to TOOLS_METADATA. This is what the model reads to decide whether to call your tool, so the description is doing real work. Be specific about when it applies.
Add a holding message
Add tools.your_tool.notification to app/assets/strings/english.yml. While the tool runs, the teacher gets this message so the wait does not look like a hang. If the key is missing, nothing is sent and a warning is logged.

Arguments the model should not choose

Some arguments come from the server, not the conversation. A user ID is the obvious case: you never want the model deciding whose data to read.

Add a builder to app/tools/internal_args.pyand it will be merged in after the model's arguments and before the call. Keep those parameters out of the JSON schema entirely.

Class IDs are special

If your tool works on one of the teacher's classes, name the parameter class_id and copy the shape used by the existing tools. The registry rewrites that property per request, injecting the real class IDs for that teacher as an enum. The model then cannot ask for a class the teacher does not teach.

Optional extras

If your tool needs	Do this
A different model or provider	Add an entry to `ToolSettings` in `app/config.py` and a matching block under `tools:` in `app/assets/config/base.yml`. Follow `solve_equation`.
Its own prompt	Add files under `app/assets/prompts/your_prompt/` and register the version in `app/assets/config/prompts.yml`.

A declared prompt with no file crashes at import

The prompt manager reads its registry when the module loads, so a version listed in prompts.yml without a matching file stops the whole application from starting. It is a fast failure, but the traceback points at import machinery rather than at your typo.

Before you open the pull request

Tools are awaited one after another, and the teacher is waiting on WhatsApp. Keep them quick, and prefer a partial answer over a long silence.
Never put a tool name in text the model might repeat. Any reply containing a registered tool name is thrown away and replaced with a generic error.
Add a test under tests/tools/. The existing ones show the pattern.

Tool

What it does

search_knowledge

Retrieves passages from the teacher's textbooks.

create_lesson_plan

Builds a structured lesson plan.

generate_exercise

Produces practice questions.

solve_equation

Works through mathematics, on its own model configuration.

generate_necta_style_exam

Produces an exam in the national format, delivered as a PDF.

The steps

Write the function

Create app/tools/tool_code/your_tool/main.py with an __init__.py beside it. Export one async function named after the tool. Return a string, which is what the model sees as the result.

Register the name

Add a member to the ToolName enum in app/tools/registry.py. The member name and its string value must match.

Map the name to the function

Import your function and add it to TOOL_FUNCTION_MAP in the same file.

Describe it to the model

Append a JSON schema entry to TOOLS_METADATA. This is what the model reads to decide whether to call your tool, so the description is doing real work. Be specific about when it applies.

Add a holding message

Add tools.your_tool.notification to app/assets/strings/english.yml. While the tool runs, the teacher gets this message so the wait does not look like a hang. If the key is missing, nothing is sent and a warning is logged.

Arguments the model should not choose

Some arguments come from the server, not the conversation. A user ID is the obvious case: you never want the model deciding whose data to read.

Add a builder to app/tools/internal_args.pyand it will be merged in after the model's arguments and before the call. Keep those parameters out of the JSON schema entirely.

Class IDs are special

Optional extras

If your tool needs

Do this

A different model or provider

Add an entry to ToolSettings in app/config.py and a matching block under tools: in app/assets/config/base.yml. Follow solve_equation.

Its own prompt

Add files under app/assets/prompts/your_prompt/ and register the version in app/assets/config/prompts.yml.

A declared prompt with no file crashes at import

Before you open the pull request

Tools are awaited one after another, and the teacher is waiting on WhatsApp. Keep them quick, and prefer a partial answer over a long silence.

Never put a tool name in text the model might repeat. Any reply containing a registered tool name is thrown away and replaced with a generic error.

Add a test under tests/tools/. The existing ones show the pattern.