opencode-skills-collection 3.1.9 → 3.1.11

package/bundled-skills/weaviate-cookbooks/references/async_client.md

@@ -0,0 +1,428 @@
+# Async Client Usage
+
+Guide for using the Weaviate Python async client in production applications (FastAPI, async frameworks).
+
+## 📚 Official Documentation Reference
+
+**For agents:** If you encounter any issues not covered here, refer to the official Weaviate documentation:
+
+- **Primary Reference**: [Weaviate Async API Documentation](https://docs.weaviate.io/weaviate/client-libraries/python/async)
+- **Python Client Reference**: [Weaviate Python Client Docs](https://docs.weaviate.io/weaviate/client-libraries/python)
+- **API Reference**: [ReadTheDocs - Python Client](https://weaviate-python-client.readthedocs.io/en/stable/)
+- **Troubleshooting**: [Community Forum](https://forum.weaviate.io/) | [GitHub Issues](https://github.com/weaviate/weaviate-python-client/issues)
+
+> **Note**: The async client (`WeaviateAsyncClient`) is available in `weaviate-client` v4.7.0+.
+
+## Connection Methods
+
+Three instantiation helpers are provided ([docs](https://docs.weaviate.io/weaviate/client-libraries/python/async#instantiation)):
+
+### Weaviate Cloud (Recommended)
+
+```python
+import weaviate
+from weaviate.classes.init import Auth
+
+# Use the official helper function for Weaviate Cloud
+client = weaviate.use_async_with_weaviate_cloud(
+    cluster_url="your-cluster.weaviate.cloud",  # Accepts hostname with or without https://
+    auth_credentials=Auth.api_key("your-api-key"),
+    headers={  # Note: parameter is "headers" not "additional_headers"
+        "X-OpenAI-Api-Key": "sk-...",
+        "X-Anthropic-Api-Key": "sk-ant-...",
+    }
+)
+
+await client.connect()  # Required! Async helpers don't auto-connect
+```
+
+**Reference**: [Weaviate Cloud Setup](https://docs.weaviate.io/weaviate/quickstart)
+
+### Self-Hosted
+
+```python
+# For local instances
+client = weaviate.use_async_with_local()
+
+# For custom endpoints
+client = weaviate.use_async_with_custom(
+    http_host="localhost",
+    http_port=8080,
+    http_secure=False,
+    grpc_host="localhost",
+    grpc_port=50051,
+    grpc_secure=False,
+)
+
+await client.connect()
+```
+
+**Reference**: [Connection Configuration](https://weaviate-python-client.readthedocs.io/en/stable/weaviate.html)
+
+### Authentication
+
+Multiple authentication modes are supported ([docs](https://docs.weaviate.io/weaviate/client-libraries/python#authentication)):
+
+```python
+from weaviate.classes.init import Auth
+
+# API Key (most common for Weaviate Cloud)
+auth = Auth.api_key("your-api-key")
+
+# Bearer Token (with optional refresh token)
+auth = Auth.bearer_token("access-token", refresh_token="refresh-token")
+
+# Client Credentials (OIDC)
+auth = Auth.client_credentials(client_secret="secret")
+
+# Client Password (OIDC Resource Owner Password flow)
+auth = Auth.client_password(username="user", password="pass")
+
+# Usage
+client = weaviate.use_async_with_weaviate_cloud(
+    cluster_url="your-cluster.weaviate.cloud",
+    auth_credentials=auth,
+)
+```
+
+## Critical Patterns
+
+### ⚠️ Connection Lifecycle
+
+**Important**: Unlike synchronous helpers, async helpers **do not connect automatically** ([docs](https://docs.weaviate.io/weaviate/client-libraries/python/async#instantiation)). You must explicitly call `.connect()` and `.close()`:
+
+```python
+# ❌ Wrong - client not connected
+client = weaviate.use_async_with_weaviate_cloud(...)
+collections = await client.collections.list_all()  # Will fail!
+
+# ✅ Correct - explicit connect/close
+client = weaviate.use_async_with_weaviate_cloud(...)
+await client.connect()
+collections = await client.collections.list_all()
+await client.close()
+```
+
+### ⚠️ Sync vs Async Methods
+
+**Key distinction** ([docs](https://docs.weaviate.io/weaviate/client-libraries/python/async#which-methods-are-async)): Methods involving server requests are async; local operations are synchronous.
+
+```python
+# Collection retrieval is SYNC (no await)
+collection = client.collections.get("MyCollection")
+
+# Operations on collections are ASYNC (need await)
+config = await collection.config.get()
+results = await collection.query.fetch_objects()
+count = await collection.aggregate.over_all()
+```
+
+**Rule:** Getting the collection object is sync; calling methods on it is async.
+
+### ⚠️ Bulk Operations
+
+**Important Note** ([docs](https://docs.weaviate.io/weaviate/client-libraries/python/async#bulk-import-operations)): For large-scale data imports, use the **synchronous client** and its batch operations. The sync client's batch methods already handle concurrency internally and are optimized for bulk operations.
+
+```python
+# ✅ For bulk imports, prefer sync client
+import weaviate
+
+with weaviate.connect_to_weaviate_cloud(...) as client:
+    collection = client.collections.get("MyCollection")
+
+    # Batch insert handles concurrency automatically
+    with collection.batch.dynamic() as batch:
+        for item in large_dataset:
+            batch.add_object(properties=item)
+```
+
+Use the async client for:
+
+- Web applications (FastAPI, Starlette)
+- Concurrent request handling
+- Interactive queries
+
+Don't use the async client for:
+
+- Bulk data imports (use sync client instead)
+
+## Context Manager Pattern (Recommended)
+
+**Best Practice** ([docs](https://docs.weaviate.io/weaviate/client-libraries/python/async#using-the-async-context-manager)): Use `async with` to automatically connect/disconnect:
+
+```python
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+@asynccontextmanager
+async def get_weaviate_client(
+    cluster_url: str,
+    api_key: str,
+    provider_headers: dict[str, str] | None = None,
+) -> AsyncGenerator[weaviate.WeaviateAsyncClient, None]:
+    """Connect to Weaviate Cloud with automatic cleanup."""
+    # Remove scheme if present
+    hostname = cluster_url.replace("https://", "").replace("http://", "")
+
+    client = weaviate.use_async_with_weaviate_cloud(
+        cluster_url=hostname,
+        auth_credentials=Auth.api_key(api_key),
+        headers=provider_headers,
+    )
+
+    try:
+        await client.connect()
+        yield client
+    finally:
+        await client.close()
+
+# Usage
+async def example():
+    async with get_weaviate_client(
+        cluster_url="your-cluster.weaviate.cloud",
+        api_key="your-key",
+    ) as client:
+        collections = await client.collections.list_all()
+```
+
+> **Note**: When using the context manager, `.connect()` and `.close()` are called automatically.
+
+## FastAPI Integration
+
+**Use Case** ([docs](https://docs.weaviate.io/weaviate/client-libraries/python/async#use-cases)): The async client excels in web frameworks like FastAPI for handling concurrent requests.
+
+Use lifespan management for shared client across requests:
+
+```python
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: connect to Weaviate
+    app.state.weaviate = weaviate.use_async_with_weaviate_cloud(
+        cluster_url="your-cluster.weaviate.cloud",
+        auth_credentials=Auth.api_key("your-key"),
+    )
+    await app.state.weaviate.connect()
+
+    yield
+
+    # Shutdown: close connection
+    await app.state.weaviate.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/collections")
+async def list_collections():
+    collections = await app.state.weaviate.collections.list_all()
+    return {"collections": list(collections.keys())}
+```
+
+**Community Discussion**: [FastAPI Best Practices](https://forum.weaviate.io/t/what-is-the-best-practice-to-use-v4-python-client-for-query-with-fastapi-or-other-async-python-framework/1245)
+
+## Common Pitfalls
+
+### 1. Parameter Name Confusion
+
+```python
+# ❌ Wrong - WeaviateAsyncClient() constructor uses different param
+client = weaviate.use_async_with_weaviate_cloud(
+    additional_headers={...}  # Wrong parameter name!
+)
+
+# ✅ Correct - use "headers" not "additional_headers"
+client = weaviate.use_async_with_weaviate_cloud(
+    headers={...}
+)
+```
+
+### 2. URL Format
+
+Both formats work with helper functions:
+
+```python
+# ✅ Both accepted
+client = weaviate.use_async_with_weaviate_cloud(
+    cluster_url="https://cluster.weaviate.cloud"  # With scheme
+)
+
+client = weaviate.use_async_with_weaviate_cloud(
+    cluster_url="cluster.weaviate.cloud"  # Without scheme
+)
+```
+
+### 3. Sync vs Async Function Names
+
+```python
+# ❌ Wrong - sync client (cannot use await)
+client = weaviate.connect_to_weaviate_cloud(...)
+await client.connect()  # TypeError!
+
+# ✅ Correct - async client
+client = weaviate.use_async_with_weaviate_cloud(...)
+await client.connect()
+```
+
+**Naming pattern:**
+
+- Sync: `connect_to_*` (e.g., `connect_to_weaviate_cloud`)
+- Async: `use_async_with_*` (e.g., `use_async_with_weaviate_cloud`)
+
+### 4. Port Configuration
+
+```python
+# ❌ Wrong - manual port config causes conflicts with Weaviate Cloud
+client = WeaviateAsyncClient(
+    connection_params=ConnectionParams.from_url(
+        url="https://cluster.weaviate.cloud",
+        grpc_port=443,  # Conflict!
+    )
+)
+
+# ✅ Correct - use helper function (handles ports automatically)
+client = weaviate.use_async_with_weaviate_cloud(
+    cluster_url="cluster.weaviate.cloud"
+)
+```
+
+**Rule:** For Weaviate Cloud, always use `use_async_with_weaviate_cloud()` — it handles HTTP (443) and gRPC (50051) ports correctly.
+
+## Multi-Cluster Example
+
+Managing connections to multiple Weaviate clusters:
+
+```python
+@asynccontextmanager
+async def get_multi_cluster_clients(
+    clusters: dict[str, dict[str, str]]
+) -> AsyncGenerator[dict[str, weaviate.WeaviateAsyncClient], None]:
+    """Connect to multiple Weaviate clusters.
+
+    Args:
+        clusters: Dict of {cluster_id: {"url": "...", "api_key": "..."}}
+    """
+    clients = {}
+
+    try:
+        # Connect to all clusters
+        for cluster_id, config in clusters.items():
+            client = weaviate.use_async_with_weaviate_cloud(
+                cluster_url=config["url"],
+                auth_credentials=Auth.api_key(config["api_key"]),
+            )
+            await client.connect()
+            clients[cluster_id] = client
+
+        yield clients
+
+    finally:
+        # Close all connections
+        for client in clients.values():
+            await client.close()
+
+# Usage
+async def example():
+    clusters = {
+        "prod": {"url": "prod.weaviate.cloud", "api_key": "key1"},
+        "dev": {"url": "dev.weaviate.cloud", "api_key": "key2"},
+    }
+
+    async with get_multi_cluster_clients(clusters) as clients:
+        prod_collections = await clients["prod"].collections.list_all()
+        dev_collections = await clients["dev"].collections.list_all()
+```
+
+## Environment Variables
+
+See [Environment Requirements](environment_requirements.md) for provider API keys.
+
+```python
+import os
+
+# Read from environment
+cluster_url = os.environ["WEAVIATE_URL"]
+api_key = os.environ["WEAVIATE_API_KEY"]
+
+# Build provider headers
+provider_headers = {}
+if openai_key := os.getenv("OPENAI_API_KEY"):
+    provider_headers["X-OpenAI-Api-Key"] = openai_key
+if anthropic_key := os.getenv("ANTHROPIC_API_KEY"):
+    provider_headers["X-Anthropic-Api-Key"] = anthropic_key
+
+client = weaviate.use_async_with_weaviate_cloud(
+    cluster_url=cluster_url,
+    auth_credentials=Auth.api_key(api_key),
+    headers=provider_headers or None,
+)
+```
+
+## Testing Async Code
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_weaviate_connection():
+    async with get_weaviate_client(
+        cluster_url="test-cluster.weaviate.cloud",
+        api_key="test-key",
+    ) as client:
+        collections = await client.collections.list_all()
+        assert isinstance(collections, dict)
+```
+
+## Quick Reference
+
+| Task             | Pattern                                       | Await?  |
+| ---------------- | --------------------------------------------- | ------- |
+| Create client    | `weaviate.use_async_with_weaviate_cloud(...)` | No      |
+| Connect          | `client.connect()`                            | **Yes** |
+| Get collection   | `client.collections.get("Name")`              | No      |
+| List collections | `client.collections.list_all()`               | **Yes** |
+| Query data       | `collection.query.fetch_objects()`            | **Yes** |
+| Get config       | `collection.config.get()`                     | **Yes** |
+| Aggregate        | `collection.aggregate.over_all()`             | **Yes** |
+| Close            | `client.close()`                              | **Yes** |
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                                                 | Solution                                            | Reference                                                                         |
+| ----------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Connection hangs indefinitely                         | Use context manager or ensure proper `.close()`     | [GitHub #753](https://github.com/weaviate/weaviate-python-client/issues/753)      |
+| Multi-worker conflicts (Gunicorn)                     | Use lifespan management, not startup hooks          | [GitHub #1292](https://github.com/weaviate/weaviate-python-client/issues/1292)    |
+| `TypeError: object NoneType can't be used in 'await'` | Use `use_async_with_*` not `connect_to_*`           | [Async API Docs](https://docs.weaviate.io/weaviate/client-libraries/python/async) |
+| Port conflicts with Weaviate Cloud                    | Use helper functions, not manual `ConnectionParams` | See "Common Pitfalls #4" above                                                    |
+
+### Getting Help
+
+**For agents:** When encountering errors:
+
+1. Check the [Common Pitfalls](#common-pitfalls) section above
+2. Search [Community Forum](https://forum.weaviate.io/) for similar issues
+3. Check [GitHub Issues](https://github.com/weaviate/weaviate-python-client/issues) for known bugs
+4. Refer to [official async documentation](https://docs.weaviate.io/weaviate/client-libraries/python/async)
+5. Review [Python client best practices](https://docs.weaviate.io/weaviate/client-libraries/python/notes-best-practices)
+
+## Additional Resources
+
+### Official Documentation
+
+- **Primary**: [Weaviate Async API](https://docs.weaviate.io/weaviate/client-libraries/python/async)
+- **Python Client**: [Main Documentation](https://docs.weaviate.io/weaviate/client-libraries/python)
+- **API Reference**: [ReadTheDocs](https://weaviate-python-client.readthedocs.io/en/stable/)
+- **Best Practices**: [Notes and Best Practices](https://docs.weaviate.io/weaviate/client-libraries/python/notes-best-practices)
+
+### Framework Integration
+
+- [FastAPI Lifespan Events](https://fastapi.tiangolo.com/advanced/events/)
+- [Python Async Context Managers](https://docs.python.org/3/reference/datamodel.html#asynchronous-context-managers)
+
+### Community
+
+- [Weaviate Community Forum](https://forum.weaviate.io/)
+- [Python Client GitHub](https://github.com/weaviate/weaviate-python-client)
+- [Weaviate Blog](https://weaviate.io/blog)

package/bundled-skills/weaviate-cookbooks/references/basic_agent.md

@@ -0,0 +1,270 @@
+# Basic Agent Cookbook
+
+Build a tool-calling AI agent with structured outputs using DSPy.
+For RAG tools, memory, and framework integrations, [see here](./agentic_rag.md).
+
+
+
+Docs to reference if needed:
+- DSPy signatures: https://dspy.ai/learn/programming/signatures/
+- DSPy language models: https://dspy.ai/learn/programming/language_models/
+- LiteLLM providers: https://docs.litellm.ai/docs/
+
+## Core Rules
+
+- Use a virtual environment via `venv`
+- Use `uv` for Python project/dependency management.
+- Do not manually author `pyproject.toml` or `uv.lock`; let `uv` generate/update them.
+- Use this install set: `uv add dspy python-dotenv`
+- Customise this cookbook to the users specification, ask them for details if not given.
+
+## Env Rules
+
+Mandatory:
+- An LLM provider API key (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`)
+- `WEAVIATE_URL`
+- `WEAVIATE_API_KEY`
+
+Optional:
+- Matching provider keys listed in `environment_requirements.md`
+
+If the user explicitly requests a non-Weaviate agent, `WEAVIATE_URL` and `WEAVIATE_API_KEY` can be omitted.
+
+## Agent Response Signature
+
+The structured output that defines what the LLM returns when selecting tools.
+
+```python
+import dspy
+from typing import Any, Dict
+
+class AgentResponse(dspy.Signature):
+
+    # Input Fields
+    history: dspy.History = dspy.InputField()
+    user_prompt: str = dspy.InputField()
+    available_tools: str = dspy.InputField()
+
+    # Output Fields
+    response: str = dspy.OutputField(
+        description="The response to the user's prompt whilst the tool is running. Update the user on the progress of their request (if a tool is picked), or the final response to the user (if no tool is picked)."
+    )
+    tool: str | None = dspy.OutputField(
+        description="The tool that needs to be used. Return None if no tool is needed."
+    )
+    tool_inputs: Dict[str, Any] | None = dspy.OutputField(
+        description=(
+            "The inputs for the tool. Return an empty dictionary (still include the field) if no inputs are needed. "
+            "The key is the name of the input, the value is the value of the input."
+        )
+    )
+```
+
+Extend `AgentResponse` as needed: add `confidence: float` for certainty scoring, `requires_clarification: bool` for follow-up questions, or modify `description` strings to shape agent behaviour for a specific domain.
+
+## Router Agent (Single Step)
+
+Wraps the agent response into a class that manages conversation history and tool execution.
+
+```python
+from typing import Callable, List, Tuple
+
+class RouterAgent:
+    def __init__(self, model: str, tools: List[Callable] = []):
+        self.tools: list[Callable] = tools
+        self.model = dspy.LM(model)
+        self.agent = dspy.ChainOfThought(AgentResponse)
+        self.conversation_history = dspy.History(messages=[])
+
+    def add_conversation_history(self, message: str, response: dspy.Prediction):
+        self.conversation_history.messages.append({"user_prompt": message, **response})
+
+    def get_tools_and_descriptions(self) -> str:
+        return "\n".join(
+            [
+                f"{tool.__name__}:\nDescription: {tool.__doc__ or ''}\nInputs: { {k: v for k, v in tool.__annotations__.items() if k != 'return'} }"
+                for tool in self.tools
+            ]
+        )
+
+    def get_response(self, user_prompt: str) -> Tuple[str, str | None]:
+        result = self.agent(
+            history=self.conversation_history,
+            user_prompt=user_prompt,
+            available_tools=self.get_tools_and_descriptions(),
+            lm=self.model,
+        )
+        self.add_conversation_history(message=user_prompt, response=result)
+        if result.tool and result.tool.lower() not in ["null", "none"]:
+            tool_function = next(
+                (tool for tool in self.tools if tool.__name__ == result.tool), None
+            )
+            if tool_function is None:
+                raise ValueError(f"Tool {result.tool} not found")
+            tool_inputs = {k: v for k, v in result.tool_inputs.items() if k != "return"}
+            tool_result = tool_function(**tool_inputs)
+        else:
+            tool_result = None
+        return result.response, tool_result
+```
+
+Usage:
+
+```python
+router = RouterAgent(
+    model="<model_name>",  # e.g. claude-sonnet-4-5, gpt-5.2, gemini-2.5-pro
+    tools=[your_tool_function]
+)
+response, tool_result = router.get_response("user query here")
+```
+
+## Tool Design
+
+Tools are Python functions. The agent reads `__name__`, `__doc__`, and `__annotations__` to decide when to use them.
+
+```python
+def your_tool(param1: str, param2: int) -> str:
+    """Clear description of what this tool does and when to use it."""
+    # tool logic here
+    return "result as string"
+```
+
+Key rules:
+- Docstrings directly influence when the agent selects the tool. Be specific: "Get current weather conditions for a city" is better than "Get weather".
+- Type hints guide what inputs the agent provides. Complex types like `filters: List[Dict]` may need additional description in the docstring.
+- Return strings or string-serializable data.
+
+
+## Sequential Multi-Step Agent
+
+For tasks requiring multiple tool calls in succession, add a followup signature and loop.
+
+Followup signature (receives `tool_output` from the previous step):
+
+```python
+class AgentFollowup(dspy.Signature):
+
+    # Input Fields
+    history: dspy.History = dspy.InputField()
+    user_prompt: str = dspy.InputField()
+    tool_output: str = dspy.InputField(description="The output of the previous tool.")
+    available_tools: str = dspy.InputField(
+        description="The available tools and their descriptions."
+    )
+
+    # Output Fields
+    response: str = dspy.OutputField(
+        description="The response to the user's prompt whilst the tool is running. Update the user on the progress of their request (if a tool is picked), or the final response to the user (if no tool is picked)."
+    )
+    tool: str | None = dspy.OutputField(
+        description="The tool that needs to be used. Return None if no tool is needed."
+    )
+    tool_inputs: Dict[str, Any] | None = dspy.OutputField(
+        description="The inputs for the tool. Return an empty dictionary (still include the field) if no inputs are needed. The key is the name of the input, the value is the value of the input.",
+    )
+```
+
+Modify `RouterAgent` to loop until the agent stops requesting tools:
+
+```python
+class RouterAgent:
+    def __init__(self, model: str, tools: List[Callable] = []):
+        self.tools: list[Callable] = tools
+        self.model = dspy.LM(model)
+        self.agent = dspy.ChainOfThought(AgentResponse)
+        self.followup_agent = dspy.ChainOfThought(AgentFollowup)
+        self.conversation_history = dspy.History(messages=[])
+
+    def add_conversation_history(self, message: str, response: dspy.Prediction):
+        self.conversation_history.messages.append({"user_prompt": message, **response})
+
+    def get_tools_and_descriptions(self) -> str:
+        return "\n".join(
+            [
+                f"{tool.__name__}:\nDescription: {tool.__doc__ or ''}\nInputs: { {k: v for k, v in tool.__annotations__.items() if k != 'return'} }"
+                for tool in self.tools
+            ]
+        )
+
+    def get_response(self, user_prompt: str) -> str:
+        result = self.agent(
+            history=self.conversation_history,
+            user_prompt=user_prompt,
+            available_tools=self.get_tools_and_descriptions(),
+            lm=self.model,
+        )
+        self.add_conversation_history(message=user_prompt, response=result)
+
+        max_iter = 10
+        iter = 0
+
+        while result.tool is not None and result.tool.lower() not in ["null", "none"]:
+            iter += 1
+            if iter > max_iter:
+                break
+
+            tool_function = next(
+                (tool for tool in self.tools if tool.__name__ == result.tool), None
+            )
+            if tool_function is None:
+                raise ValueError(f"Tool {result.tool} not found")
+
+            tool_inputs = {k: v for k, v in result.tool_inputs.items() if k != "return"}
+            tool_result = tool_function(**tool_inputs)
+
+            result = self.followup_agent(
+                history=self.conversation_history,
+                tool_output=tool_result,
+                available_tools=self.get_tools_and_descriptions(),
+                lm=self.model,
+            )
+            self.add_conversation_history(message=tool_result, response=result)
+
+        return result.response
+```
+
+`max_iter` controls how many tool calls can occur before forced termination. Increase for complex multi-step tasks, decrease to limit costs and runaway loops.
+
+## User-specific Customisations
+
+If not specified ask the user about these points before implementing their respective strategies:
+
+**LLM Framework**
+
+You can use DSPy (works with all LiteLLM providers) or LiteLLM itself.
+
+- DSPy: https://dspy.ai/learn/programming/language_models/
+- LiteLLM: https://docs.litellm.ai/docs/
+
+Alternatively, users can use a single model provider. What model provider will they use?
+
+- OpenAI (https://platform.openai.com/docs/libraries)
+- Anthropic (https://platform.claude.com/docs/)
+- Google GenAI (https://ai.google.dev/gemini-api/docs/libraries)
+- Other (such as locally hosted models), use best judgement
+
+These may require additional installs.
+
+**Model Selection**
+
+What model(s) will the user use? Consider a mixed approach: capable model for main agent routing, cheaper model for auxiliary tasks like memory creation.
+
+**Tools**
+
+What tools does the user need? List their functions, inputs, and expected outputs. The agent is only as capable as its tools.
+
+**Single-step vs Multi-step**
+
+Does the user need a single tool call per query, or should the agent chain multiple tools in sequence? Only use multi-step if the use case requires it.
+
+## Troubleshooting
+
+- DSPy signature warnings about missing fields: ensure all input fields are passed or mark optional fields appropriately.
+- Tool not found errors: ensure tool function names match exactly what the agent outputs.
+- Agent loops indefinitely: lower `max_iter` or add more explicit termination conditions.
+- For any other issues, refer to the official library/package documentation and use web search extensively for troubleshooting.
+
+## Done Criteria
+
+- Create test scripts to check each function works independently with test data. Tear down tests after completion, or create a proper test suite with pytest (requires install)
+- User has completed specification of the app.