docs: add GitBook setup, fix broken links, and generate API reference

.github/workflows/sync-gitbook-docs.yaml

@@ -5,6 +5,8 @@ on:
     branches: [main]
     paths:
       - 'docs/**'
+      - 'src/**'
+      - 'scripts/generate_api_docs.py'
       - '.gitbook.yaml'
   workflow_dispatch:
 
@@ -19,6 +21,13 @@ jobs:
         with:
           fetch-depth: 0
 
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.11"
+
+      - name: Generate API reference docs
+        run: uv run --no-dev python scripts/generate_api_docs.py
+
       - name: Sync docs to gitbook-docs branch
         run: |
           git config user.name "github-actions[bot]"

.gitignore

@@ -1,4 +1,5 @@
-# Cookbook generated files
+# Generated files
+docs/api/
 docs/cookbook/sensitive-info
 
 uv.lock

docs/SUMMARY.md

@@ -19,3 +19,13 @@
 * [Callbacks](cookbook/callbacks.md)
 * [Serve over A2A](cookbook/serve-a2a.md)
 * [Local LLM](cookbook/agent-with-local-llm.md)
+
+## API Reference
+
+* [Agent](api/agent.md)
+* [Config](api/config.md)
+* [Callbacks](api/callbacks.md)
+* [Tracing](api/tracing.md)
+* [Evaluation](api/evaluation.md)
+* [Tools](api/tools.md)
+* [Serving](api/serving.md)

docs/callbacks.md

@@ -4,7 +4,7 @@ Callbacks provide hooks into the lifecycle of an `TinyAgent` execution. Using ca
 
 ## Implementing Callbacks
 
-All callbacks must inherit from the base [Callback](../api/callbacks.md) class and can choose to implement any subset of the available callback methods. These methods include:
+All callbacks must inherit from the base [Callback](api/callbacks.md#callback) class and can choose to implement any subset of the available callback methods. These methods include:
 
 | Callback Method | When It Fires | Example Use Cases |
 |:----------------:|:------------:|:----------------|
@@ -23,15 +23,15 @@ def before_llm_call(self, context: Context, *args, **kwargs) -> Context:
 
 ## Managing State (`Context`)
 
-During an agent run (`agent.run_async` or `agent.run`), a unique [Context](../api/callbacks.md) object is created and shared across all callbacks.
+During an agent run (`agent.run_async` or `agent.run`), a unique [Context](api/callbacks.md#context) object is created and shared across all callbacks.
 
 Use `Context.shared` (a dictionary) to persist data across different steps and callbacks.
 
 > Note: The `Context` object is mutable. You should modify `Context.shared` directly and return the same object.
 
 `tinyagent` populates the `Context.current_span` property so that callbacks can access information in a framework-agnostic way.
 
-You can see what attributes are available for LLM Calls and Tool Executions by examining the [GenAI](../api/tracing.md) class.
+You can see what attributes are available for LLM Calls and Tool Executions by examining the [GenAI](api/tracing.md#genai) class.
 
 **Common Pattern**: Initialize a counter in one callback and check it in another.
 
@@ -59,7 +59,7 @@ Raising any exception from a callback immediately halts the agent loop. Use this
 
 ### Using `AgentCancel` (Recommended)
 
-For intentional cancellation (rate limits, guardrails, validation), subclass [AgentCancel](../api/agent.md). These exceptions propagate directly to your code, allowing you to catch them by their specific type:
+For intentional cancellation (rate limits, guardrails, validation), subclass [AgentCancel](api/agent.md#agentcancel). These exceptions propagate directly to your code, allowing you to catch them by their specific type:
 
 ```python
 from tinyagent import AgentCancel, AgentConfig, TinyAgent
@@ -94,7 +94,7 @@ except SearchLimitReached as e:
 
 ### Using Regular Exceptions
 
-Regular exceptions (like `RuntimeError`) are automatically wrapped in [AgentRunError](../api/agent.md) by the framework, which provides access to the execution trace but requires you to inspect the wrapped exception:
+Regular exceptions (like `RuntimeError`) are automatically wrapped in [AgentRunError](api/agent.md#agentrunerror) by the framework, which provides access to the execution trace but requires you to inspect the wrapped exception:
 
 ```python
 from tinyagent import AgentConfig, AgentRunError, TinyAgent
@@ -204,7 +204,7 @@ Advanced designs such as safety guardrails or custom side-effects can be integra
 
 `tinyagent` comes with a set of default callbacks that will be used by default (if you don't pass a value to `AgentConfig.callbacks`):
 
-- [ConsolePrintSpan](../api/callbacks.md)
+- [ConsolePrintSpan](api/callbacks.md#consoleprintspan)
 
 If you want to disable these default callbacks, you can pass an empty list:
 
@@ -228,7 +228,7 @@ Callbacks are provided to the agent using the `AgentConfig.callbacks` property.
 
 #### Extending default callbacks
 
-`tinyagent` includes default callbacks (like console logging). Use [get_default_callbacks](../api/callbacks.md) to keep them:
+`tinyagent` includes default callbacks (like console logging). Use [get_default_callbacks](api/callbacks.md#get_default_callbacks) to keep them:
 
 ```py
 from tinyagent import AgentConfig, TinyAgent

docs/cookbook/agent-with-local-llm.md

@@ -60,7 +60,7 @@ We can simply pass to the AgentConfig of `tinyagent` as a model argument (`num_c
     )
 ```
 
-References: [AgentConfig](../api/config.md), [num_ctx](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values)
+References: [AgentConfig](../api/config.md#agentconfig), [num_ctx](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values)
 
 All four of the models above have a max context length of 128k tokens, but if you have limited RAM if you
 set it to 128k it might cause you memory issues. For this example, we will set it to 32,000 tokens and provide a relatively small codebase.

docs/cookbook/agent_with_local_llm.ipynb

@@ -87,7 +87,7 @@
     "    )\n",
     "```\n",
     "\n",
-    "References: [AgentConfig](https://docs.mozilla.ai/tinyagent/api/config/), [num_ctx](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values)\n",
+    "References: [AgentConfig](https://github.com/mozilla-ai/tinyagent/blob/main/src/tinyagent/config.py), [num_ctx](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values)\n",
     "\n",
     "All four of the models above have a max context length of 128k tokens, but if you have limited RAM if you\n",
     "set it to 128k it might cause you memory issues. For this example, we will set it to 32,000 tokens and provide a relatively small codebase.\n",

docs/cookbook/callbacks.ipynb

@@ -11,7 +11,7 @@
     "We'll build three callbacks of increasing complexity: counting tool usage, enforcing \n",
     "rate limits, and protecting sensitive data.\n",
     "\n",
-    "You can find more information about callbacks in the [docs](https://docs.mozilla.ai/tinyagent/agents/callbacks/)"
+    "You can find more information about callbacks in the [docs](https://docs.mozilla.ai/tinyagent/guides/callbacks/)"
    ]
   },
   {
@@ -89,7 +89,7 @@
    "source": [
     "`tinyagent` comes with a default callback that will always be used unless you pass a value to `AgentConfig.callbacks`:\n",
     "\n",
-    "- [`ConsolePrintSpan`](https://docs.mozilla.ai/tinyagent/api/callbacks/#tinyagent.callbacks.span_print.ConsolePrintSpan)"
+    "- [`ConsolePrintSpan`](https://docs.mozilla.ai/tinyagent/guides/callbacks/#default-callbacks)"
    ]
   },
   {
@@ -237,7 +237,7 @@
    "source": [
     "## Bonus : Protect Sensitive Data\n",
     "\n",
-    "Beyond stopping the agent, callbacks can also **modify data** before it gets logged to your [traces](https://docs.mozilla.ai/tinyagent/tracing/). This is critical for preventing Sensitive Information (PII) from leaking into your logs. \n",
+    "Beyond stopping the agent, callbacks can also **modify data** before it gets logged to your [traces](https://docs.mozilla.ai/tinyagent/guides/tracing/). This is critical for preventing Sensitive Information (PII) from leaking into your logs. \n",
     "\n",
     "In the example below, we are going to implement a callback that:\n",
     "1. Detects `INPUT_MESSAGES` in `Context.current_span`. \n",
@@ -290,7 +290,7 @@
    "source": [
     "We can now provide our callback to the agent. \n",
     "\n",
-    "You can find more information in [our docs](https://docs.mozilla.ai/tinyagent/agents/callbacks/#providing-your-own-callbacks)."
+    "You can find more information in [our docs](https://docs.mozilla.ai/tinyagent/guides/callbacks/#providing-your-own-callbacks)."
    ]
   },
   {

docs/cookbook/callbacks.md

@@ -4,7 +4,7 @@ This cookbook shows you how to monitor, control, and secure your agents using ca
 We'll build three callbacks of increasing complexity: counting tool usage, enforcing
 rate limits, and protecting sensitive data.
 
-You can find more information about callbacks in the [docs](../agents/callbacks.md)
+You can find more information about callbacks in the [docs](../callbacks.md)
 
 ```python
 %pip install 'mozilla-ai-tinyagent' --quiet
@@ -46,7 +46,7 @@ from tinyagent.tools import search_web
 
 `tinyagent` comes with a default callback that will always be used unless you pass a value to `AgentConfig.callbacks`:
 
-- [`ConsolePrintSpan`](../api/callbacks.md)
+- [`ConsolePrintSpan`](../api/callbacks.md#consoleprintspan)
 
 ```python
 agent = TinyAgent.create(
@@ -184,7 +184,7 @@ class SensitiveDataOffloader(Callback):
 
 We can now provide our callback to the agent.
 
-You can find more information in [our docs](../agents/callbacks.md#providing-your-own-callbacks).
+You can find more information in [our docs](../callbacks.md#registering-your-own-callbacks).
 
 ```python
 from tinyagent.callbacks import get_default_callbacks

docs/models.md

@@ -6,7 +6,7 @@ Model configuration in `tinyagent` is designed to be consistent across all suppo
 
 ## Configuration Parameters
 
-The model configuration is defined through several parameters in [AgentConfig](../api/config.md):
+The model configuration is defined through several parameters in [AgentConfig](api/config.md#agentconfig):
 
 The `model_id` parameter selects which language model your agent will use. The format depends on the provider.
 

docs/serving.md

@@ -8,7 +8,7 @@
 
 ## Configuring and Serving Agents
 
-You can configure and serve an agent using the [A2AServingConfig](api/config.md) or [MCPServingConfig](api/config.md) and the `TinyAgent.serve_async` method.
+You can configure and serve an agent using the [A2AServingConfig](api/config.md#a2aservingconfig) or [MCPServingConfig](api/config.md#mcpservingconfig) and the `TinyAgent.serve_async` method.
 
 For illustrative purposes, we are going to define 2 separate scripts, each defining an agent to answer questions about a specific agent framework (either Google ADK or OpenAI Agents SDK):
 
@@ -113,7 +113,7 @@ of each protocol:
 - [A2A Client](https://a2a-protocol.org/latest/tutorials/python/6-interact-with-server/#understanding-the-client-code)
 - [MCP Client](https://modelcontextprotocol.io/quickstart/client)
 
-Alternatively, as described in [Using Agents-As-Tools](agents/tools.md#using-agents-as-tools), we can run another python script containing the main agent that can use the served agents:
+Alternatively, as described in [Using Agents-As-Tools](tools.md#using-agents-as-tools), we can run another python script containing the main agent that can use the served agents:
 
 ```python
 import asyncio
@@ -149,4 +149,3 @@ if __name__ == "__main__":
 Check out our cookbook example for building and serving an agent via A2A:
 
 - [Serve an Agent with A2A](cookbook/serve-a2a.md)
-- [Use an A2A Agent as a tool](cookbook/a2a-as-tool.md)

docs/tools.md

@@ -17,7 +17,7 @@ Under the hood, `tinyagent` takes care of wrapping the
 tool so it becomes usable by the selected framework.
 
 {% hint style="success" %}
-Check all the [built-in callable tools](../api/tools.md) that tinyagent provides.
+Check all the [built-in callable tools](api/tools.md) that tinyagent provides.
 {% endhint %}
 
 ```python
@@ -130,7 +130,7 @@ main_agent = await TinyAgent.create_async(
 
 ## MCP
 
-MCP can either be run locally ([MCPStdio](../api/config.md)) or you can connect to an MCP that is running elsewhere (using either [MCPSse](../api/config.md) or [MCPStreamableHttp](../api/config.md)).
+MCP can either be run locally ([MCPStdio](api/config.md#mcpstdio)) or you can connect to an MCP that is running elsewhere (using either [MCPSse](api/config.md#mcpsse) or [MCPStreamableHttp](api/config.md#mcpstreamablehttp)).
 
 {% hint style="success" %}
 There are tools like [SuperGateway](https://github.com/supercorp-ai/supergateway) providing an easy way to turn a Stdio server into an SSE server.
@@ -142,7 +142,7 @@ The SSE remote transport has been deprecated as of [MCP specification version 20
 
 #### MCP (Stdio)
 
-See the [MCPStdio](../api/config.md) API Reference.
+See the [MCPStdio](api/config.md#mcpstdio) API Reference.
 
 ```python
 from tinyagent import AgentConfig
@@ -162,7 +162,7 @@ main_agent = AgentConfig(
 
 #### MCP (Streamable HTTP)
 
-See the [MCPStreamableHttp](../api/config.md) API Reference.
+See the [MCPStreamableHttp](api/config.md#mcpstreamablehttp) API Reference.
 
 ```python
 from tinyagent import AgentConfig
@@ -180,7 +180,7 @@ main_agent = AgentConfig(
 
 #### MCP (SSE)
 
-See the [MCPSse](../api/config.md) API Reference.
+See the [MCPSse](api/config.md#mcpsse) API Reference.
 
 ```python
 from tinyagent import AgentConfig