diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fffeba4199..ad59feef3b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,7 +29,7 @@ jobs: - name: Deploy PR Preview uses: rossjrw/pr-preview-action@v1 with: - token: ${{ secrets.GH_TOKEN }} + token: ${{ secrets.GITHUB_TOKEN }} preview-branch: gh-pages source-dir: ./build/ umbrella-dir: pr-preview \ No newline at end of file diff --git a/docs/agent-cookbook/advanced-patterns.md b/docs/agent-cookbook/advanced-patterns.md new file mode 100644 index 0000000000..94be2f0957 --- /dev/null +++ b/docs/agent-cookbook/advanced-patterns.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 5 +--- + +# Advanced Patterns + +Explore complex agent scenarios and optimization techniques. + +This section will contain: +- Multi-agent systems +- Complex workflows +- Performance optimization +- Advanced techniques diff --git a/docs/agent-cookbook/building-agents.md b/docs/agent-cookbook/building-agents.md new file mode 100644 index 0000000000..288b03950f --- /dev/null +++ b/docs/agent-cookbook/building-agents.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 2 +--- + +# Building Agents + +Step-by-step guides for designing and implementing custom agents. + +This section will contain: +- Agent design patterns +- Implementation guides +- State management +- Decision-making systems diff --git a/docs/agent-cookbook/deployment.md b/docs/agent-cookbook/deployment.md new file mode 100644 index 0000000000..3639a6215e --- /dev/null +++ b/docs/agent-cookbook/deployment.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 4 +--- + +# Deployment + +Best practices for deploying agents to production environments. + +This section will contain: +- Deployment strategies +- Scaling agents +- Monitoring and logging +- Performance optimization diff --git a/docs/agent-cookbook/faq.md b/docs/agent-cookbook/faq.md new file mode 100644 index 0000000000..5869891998 --- /dev/null +++ b/docs/agent-cookbook/faq.md @@ -0,0 +1,273 @@ +--- +sidebar_position: 3 +--- + +# FAQ + +Frequently asked questions about Agent Cookbook. + +## Getting Started + +### Q: What do I need to get started? + +A: Just three things: +1. Python 3.10+ (check with `python --version`) +2. An LLM API key (OpenAI, Anthropic, AWS Bedrock, or LiteLLM) +3. A Teradata SQL Engine connection (free tier available) + +See [Running the Recipes](/agent-cookbook/running-the-recipes/) for setup. + +### Q: Can I use Agent Cookbook without Teradata? + +A: Currently, Agent Cookbook is designed for Teradata. However, the architecture could be adapted for other databases. Check the [GitHub issues](https://github.com/Teradata/teradata_agent_cookbook/issues) for community efforts. + +### Q: How much does this cost? + +A: Agent Cookbook is **free and open source**. LLM API costs depend on your provider: +- **OpenAI**: ~$0.002/1k tokens (GPT-3.5) or more for GPT-4 +- **Anthropic**: Similar pricing +- **AWS Bedrock**: Pay-per-token model +- **LiteLLM**: Lowest cost (proxies multiple providers) + +Test with LiteLLM first for the lowest cost. + +## LLM Providers + +### Q: Which LLM provider should I use? + +A: **Start with LiteLLM** or **OpenAI** (GPT-3.5): +- **LiteLLM**: Lowest cost, good quality, proxy to multiple models +- **OpenAI**: GPT-4 is excellent but pricier +- **Anthropic**: Claude 3 has good reasoning +- **AWS Bedrock**: Good if you're already on AWS + +See [Why the Cookbook: LLM Providers](/agent-cookbook/why-the-cookbook/llm-providers/) for configuration. + +### Q: Can I switch LLM providers mid-conversation? + +A: **No** - agents run with one LLM per session. But you can easily select a different provider for the next query through the UI. + +### Q: My LLM responses are inaccurate. How do I improve them? + +A: Try: +1. **Better prompts** - Edit the system prompt in `agent.py` +2. **More context** - Include more schema/table info in tool descriptions +3. **Better LLM** - Upgrade to GPT-4 or Claude 3 +4. **In-context examples** - Add few-shot examples to prompts +5. **Reduce hallucination** - Add stricter constraints on what the agent can query + +See [Why the Cookbook: Server Factory](/agent-cookbook/why-the-cookbook/server-factory/) for details. + +### Q: LiteLLM says "Model not found". How do I fix it? + +A: Verify your model name matches the provider: +```python +# OpenAI models +gpt-3.5-turbo +gpt-4 +gpt-4-turbo + +# Anthropic models +claude-3-opus +claude-3-sonnet +claude-3-haiku + +# AWS Bedrock models (use arn or model ID) +anthropic.claude-3-opus-20240229-v1:0 +``` + +Update your `.env` with the correct model name. + +## Running Recipes + +### Q: How do I run just one recipe instead of all? + +A: Use the launcher with the recipe name: + +```bash +python launcher.py data-analyst +``` + +See [Running the Recipes](/agent-cookbook/running-the-recipes/) for options. + +### Q: The UI won't connect to my recipe. What's wrong? + +A: Check: +1. Recipe server is running (should see `Uvicorn running on 0.0.0.0:8001`) +2. Port isn't blocked by firewall +3. `.env` file has valid Teradata credentials +4. No typos in `recipe.yaml` port number + +Debug with: +```bash +curl http://localhost:8001/info +# Should return recipe metadata +``` + +### Q: Can I run recipes on different machines? + +A: It's possible but requires: +- Network connectivity between UI machine and recipe servers +- Firewall rules allowing traffic on ports 8001-8007 +- Shared `.env` file or per-machine config + +For production, see the [Running the Recipes](../running-the-recipes/) guide for advanced deployments (coming soon). + +### Q: How do I make a recipe call another recipe? + +A: Add an HTTP tool that calls another recipe's endpoint: + +```python +import httpx + +class RecipeChainTool: + async def call_other_recipe(self, query): + async with httpx.AsyncClient() as client: + response = await client.post( + "http://localhost:8002/invoke", + json={"query": query} + ) + return response.json() +``` + +See [Expanding with Your Agents](/agent-cookbook/running-the-recipes/expanding-agents/) for more details. + +## Architecture & Concepts + +### Q: What's the difference between data-analyst and data-analyst-multiturn? + +A: **data-analyst**: Handles each query independently +- Pro: Simpler, lower latency +- Con: Can't reference previous queries + +**data-analyst-multiturn**: Maintains conversation history +- Pro: "Follow-up to your earlier query..." works +- Con: Higher latency, more expensive + +### Q: What's the server factory pattern? + +A: A pattern where `server_factory.py` does all the repetitive FastAPI setup (authentication, error handling, logging) and your recipe just defines an agent. This minimizes boilerplate. + +See [Why the Cookbook: Server Factory Pattern](/agent-cookbook/why-the-cookbook/server-factory/) for details. + +### Q: How does the launcher discover recipes? + +A: The launcher: +1. Scans `recipes/` directory +2. Finds all `recipe.yaml` files +3. Reads port, LLM providers, and other metadata +4. Starts each recipe server with environment variables + +New recipes are automatically discovered - no registration needed! + +## Advanced Topics + +### Q: Can I add authentication to my recipe? + +A: Yes! The server factory supports: +- API key validation +- JWT tokens +- OAuth2 + +See `shared/auth.py` for templates. + +### Q: How do I add logging/monitoring? + +A: All servers use Python `logging`. For production, integrate: +- **DataDog**: Python datadog agent +- **New Relic**: APM monitoring +- **ELK Stack**: Elasticsearch, Logstash, Kibana + +Logs are printed to console and can be forwarded. + +### Q: Can I run recipes in a container? + +A: Yes! Each recipe has a `Dockerfile`. Start with Docker: + +```bash +docker build -t my-recipe recipes/basic_agents/data_analyst +docker run -p 8001:8001 --env-file .env my-recipe +``` + +### Q: How do I deploy to Kubernetes? + +A: A: Create Kubernetes manifests for each recipe service. See examples in `kubernetes/` folder (if available). + +### Q: Can I use Vector Databases instead of SQL? + +A: **vector-search** recipe does exactly that! It: +- Embeds documents or data +- Stores in vector index +- Retrieves similar items +- Passes to agent + +More advanced recipes (including vector-search) are coming soon. + +## Troubleshooting + +### Q: "ModuleNotFoundError: No module named 'shared'" + +A: Set `PYTHONPATH` before running: +```bash +export PYTHONPATH="${PYTHONPATH}:$(pwd)" +python launcher.py data-analyst +``` + +Or run from project root. + +### Q: My agent generates invalid SQL. How do I fix it? + +A: 1. Check your LLM model - GPT-3.5 struggles with complex SQL +2. Add SQL examples to the system prompt +3. Use a syntax validator tool before execution +4. Simplify the schema - fewer tables = better SQL + +Review the [Why the Cookbook](../why-the-cookbook/) section for agent architecture details. + +### Q: I'm running out of memory. What do I do? + +A: Run fewer recipes: +```bash +python launcher.py data-analyst governed +# Instead of: python launcher.py all +``` + +Or increase system memory/swap. + +### Q: The UI is slow. Why? + +A: Possible causes: +1. **LLM latency** - OpenAI/Anthropic may be busy +2. **SQL query** - Complex database query taking time +3. **Network** - Slow connection to Teradata + +Check recipe logs to identify bottleneck. + +### Q: How do I reset everything and start fresh? + +A: ```bash +# Warning: This deletes all data! +rm -rf venv/ +rm -f .env +python launcher.py all --setup +``` + +## Community & Support + +### Q: Where can I get help? + +A: - **GitHub Issues**: https://github.com/Teradata/teradata_agent_cookbook +- **Documentation**: See [Getting Started](../getting-started/) +- **Community**: Check GitHub Discussions + +### Q: How do I contribute? + +A: See CONTRIBUTING.md in the GitHub repo. + +### Q: Is there a roadmap? + +A: Yes! Check [What's New](/whats-new/release-notes/) for planned features and recent releases. + +--- + +**Still have questions?** [Open a GitHub issue](https://github.com/Teradata/teradata_agent_cookbook/issues/new) or ask in Discussions! diff --git a/docs/agent-cookbook/getting-started.md b/docs/agent-cookbook/getting-started.md new file mode 100644 index 0000000000..4119175d78 --- /dev/null +++ b/docs/agent-cookbook/getting-started.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 1 +--- + +# Getting Started with Agents + +Learn the fundamentals of agent architecture and design patterns. + +This section will contain: +- Agent concepts and architecture +- Design patterns +- Your first agent +- Core components diff --git a/docs/agent-cookbook/integration.md b/docs/agent-cookbook/integration.md new file mode 100644 index 0000000000..08caa8be06 --- /dev/null +++ b/docs/agent-cookbook/integration.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 3 +--- + +# Integration + +Connect your agents with external systems, APIs, and data sources. + +This section will contain: +- API integrations +- Data source connections +- Tool integration +- Plugin development diff --git a/docs/agent-cookbook/running-the-recipes/agent-servers-ui.md b/docs/agent-cookbook/running-the-recipes/agent-servers-ui.md new file mode 100644 index 0000000000..2f46ac5893 --- /dev/null +++ b/docs/agent-cookbook/running-the-recipes/agent-servers-ui.md @@ -0,0 +1,218 @@ +--- +sidebar_position: 3 +--- + +# Agent Servers and UI Architecture + +Understand how the launcher, servers, and UI work together. + +## Architecture Overview + +``` +┌────────────────────────────────────────────────────────┐ +│ Browser (Port 5173) │ +│ Agent Cookbook Web UI (React) │ +└────────────────────────────────────────────────────────┘ + ↓ GET /info, POST /invoke + ┌─────────────────────────────────────┐ + │ Launcher (Python orchestrator) │ + │ - Discovers recipes │ + │ - Starts services │ + │ - Manages ports │ + └─────────────────────────────────────┘ + ↓ HTTP requests distributed + ┌─────────┴──────────┬──────────┬──────────┐ + ↓ ↓ ↓ ↓ +┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────┐ +│ Port │ │ Port │ │ Port │ │ Port │ +│ 8001 │ │ 8002 │ │ 8003 │ │ ... │ +│ │ │ │ │ │ │ │ +│data- │ │data- │ │data- │ │other │ +│analyst │ │analyst- │ │analyst- │ │recipes +│ (FastAPI)│ │multiturn│ │dbt │ │ │ +└─────────┘ └─────────┘ └─────────┘ └──────┘ + ↓ SQL queries ↓ ↓ + └──────────────┬────┴──────────────┘ + ↓ + ┌──────────────┐ + │ Teradata │ + │ Database │ + └──────────────┘ +``` + +## The Launcher + +The launcher orchestrates everything: + +```python +# Start all recipes +python launcher.py all + +# Or specific recipes +python launcher.py data-analyst data-analyst-multiturn + +# With setup phase +python launcher.py all --setup +``` + +### Launcher Discovery Process + +1. **Scans `recipes/` directory** - Finds all `recipe.yaml` files +2. **Reads metadata** - Port, LLM providers, dependencies +3. **Starts services** - One FastAPI server per port +4. **Launches UI** - React app connects to all services +5. **Displays URLs** - Shows where everything is running + +### Example Output + +``` +[INFO] Starting Agent Cookbook... +[INFO] Found 1 recipe: data-analyst +[INFO] Starting data-analyst on port 8001... +[INFO] Server running on http://localhost:8001/info +[INFO] Starting UI on port 5173... +[INFO] UI ready: http://localhost:5173 +[INFO] Press Ctrl+C to stop all services +``` + +## Agent Servers (FastAPI) + +Each recipe runs as a FastAPI server with uniform endpoints. + +### Server.py (Boilerplate) + +```python +from server_factory import create_app +from agent import create_agent + +app = create_app(recipe_path=__file__, agent_factory=create_agent) + +if __name__ == "__main__": + import uvicorn + import os + port = int(os.getenv("PORT", 8001)) + uvicorn.run(app, host="0.0.0.0", port=port) +``` + +The factory provides: +- ✓ `/info` - Metadata endpoint +- ✓ `/invoke` - Agent execution +- ✓ `/health` - Health check + +### Recipe Configuration (recipe.yaml) + +As Daniel explains: + +> "We have a Python server. This is gonna be an individual script per recipe which you can see here in server.py from server factory." + +```yaml +name: "Data Analyst" +description: "SQL query generation and execution" +family: "basic-agents" +port: 8001 +llm_providers: + - openai + - anthropic + - bedrock + - litellm +``` + +## The Web UI (React) + +The React app at `localhost:5173` provides: + +### Features + +1. **Recipe Selector** - Dropdown of available agents +2. **Chat Interface** - Send questions, receive responses +3. **LLM Provider Choice** - Switch between providers +4. **Response Display** - See results and metadata +5. **History** - Track queries and responses + +### UI-to-Server Flow + +```javascript +// User submits query in UI +1. UI sends: POST /invoke to http://localhost:8001/invoke + Body: { query: "How many customers?", llm: "openai" } + +2. Server (FastAPI) receives and calls agent + +3. Agent: + - Connects to Teradata + - Generates SQL + - Executes query + - Returns results + +4. Server returns: { status: "success", data: { result: "..." } } + +5. UI displays results to user +``` + +## Ports and Services + +| Service | Port | Purpose | +|---------|------|---------| +| data-analyst | 8001 | SQL generation | +| data-analyst-multiturn | 8002 | With memory | +| data-analyst-dbt | 8003 | Schema discovery | +| data-analyst-mcp | 8004 | MCP tools | +| governed | 8005 | With security | +| vector-search | 8006 | Semantic search | +| open-analytics | 8007 | Computation | +| UI | 5173 | Web interface | + +## Request Flow Example + +**User asks**: "How many customers in New York?" + +``` +1. UI (localhost:5173) → POST http://localhost:8001/invoke + { + "query": "How many customers in New York?", + "llm": "openai" + } + +2. FastAPI Server + - Calls create_agent() + - Instantiates LLM client + - Loads available tools + +3. Agent Logic + - Constructs prompt with schema + - LLM generates: SELECT COUNT(*) FROM customers WHERE state='NY' + - Validates SQL + - Executes on Teradata + +4. Response + { + "status": "success", + "data": { + "result": "1,325 customers", + "sql_executed": "SELECT COUNT(*)", + "tokens_used": 127 + } + } + +5. UI displays result to user +``` + +## Monitoring Services + +```bash +# Check if server is running +curl http://localhost:8001/health + +# Get server info +curl http://localhost:8001/info + +# Invoke agent manually +curl -X POST http://localhost:8001/invoke \ + -H "Content-Type: application/json" \ + -d '{"query": "Show me tables"}' +``` + +## Next Steps + +- **[Running Data Analyst](/agent-cookbook/running-the-recipes/data-analyst-recipe/)** - Hands-on walkthrough +- **[Expanding with Your Agents](/agent-cookbook/running-the-recipes/expanding-agents/)** - Build your own diff --git a/docs/agent-cookbook/running-the-recipes/data-analyst-recipe.md b/docs/agent-cookbook/running-the-recipes/data-analyst-recipe.md new file mode 100644 index 0000000000..e46683b9ff --- /dev/null +++ b/docs/agent-cookbook/running-the-recipes/data-analyst-recipe.md @@ -0,0 +1,202 @@ +--- +sidebar_position: 4 +--- + +# Running the Data Analyst Recipe + +Your first hands-on walkthrough with the data-analyst agent. + +## Starting the Recipe + +```bash +# Option 1: Just data-analyst +python launcher.py data-analyst + +# Option 2: All recipes +python launcher.py all + +# Option 3: With setup (first time) +python launcher.py data-analyst --setup +``` + +## Expected Output + +``` +[INFO] Starting data-analyst on port 8001... +[INFO] Server running on http://localhost:8001 +[INFO] Ready to receive requests +``` + +## Testing via Command Line + +### Test 1: Get Server Info + +```bash +curl http://localhost:8001/info +``` + +**Response**: +```json +{ + "name": "Data Analyst", + "description": "SQL query generation and execution", + "port": 8001, + "llm_providers": ["openai", "anthropic", "bedrock", "litellm"] +} +``` + +### Test 2: List Available Tables + +```bash +curl -X POST http://localhost:8001/invoke \ + -H "Content-Type: application/json" \ + -d '{ + "query": "What tables are available?", + "llm": "openai" + }' +``` + +**Response**: +```json +{ + "status": "success", + "data": { + "result": "Available tables: customers, orders, products, ...", + "metadata": { + "llm_model": "gpt-3.5-turbo", + "tokens_used": 45 + } + } +} +``` + +### Test 3: Query Customer Data + +```bash +curl -X POST http://localhost:8001/invoke \ + -H "Content-Type: application/json" \ + -d '{ + "query": "How many customers do we have?", + "llm": "openai" + }' +``` + +**Response**: +```json +{ + "status": "success", + "data": { + "result": "We have 1,000 customers.", + "sql_executed": "SELECT COUNT(*) FROM customers;", + "tokens_used": 120 + } +} +``` + +## Testing via Web UI + +1. **Open browser**: `http://localhost:5173` +2. **Select recipe**: Choose "data-analyst" from dropdown +3. **Select LLM**: Choose "OpenAI" or "LiteLLM" +4. **Type query**: "What's our top product by revenue?" +5. **Send**: Click send or press Enter +6. **Review**: See results and SQL executed + +## Example Queries to Try + +### Basic Queries +- "How many orders do we have?" +- "List all product categories" +- "What's the oldest order?" + +### Analysis Queries +- "What's our revenue this month?" +- "Who is our top customer?" +- "Which products need restocking?" + +### Complex Queries +- "Compare revenue by region" +- "Find customers with more than 10 orders" +- "Show month-over-month sales growth" + +## Understanding the Data + +The default dataset includes: + +- **customers** - Customer information (ID, name, location) +- **orders** - Order records (date, customer_id, total) +- **products** - Product catalog (name, category, price) +- **order_items** - Order line items (order_id, product_id, quantity) + +## How It Works Behind the Scenes + +As explained in the video: + +> "We have a very simple shorthand here with the start agents. This one displays what are the agents that are available. We can choose the number 1 and number 5, which is the UI...for example, I can ask here what tables are available to me in this system, and this agent will reply me with what tables are available." + +**The flow**: + +1. **User question** → "How many customers?" +2. **LLM sees schema** → Knows tables and columns +3. **LLM generates SQL** → `SELECT COUNT(*) FROM customers` +4. **SQL validation** → Check syntax +5. **Execute** → Query runs on Teradata +6. **Format response** → "We have 1,000 customers" + +## Agent Implementation + +The agent logic lives in `recipes/basic_agents/data_analyst/agent.py`: + +```python +def create_agent(llm, tools, config): + """ + Simple SQL-based agent that: + 1. Sees the schema + 2. Generates SQL + 3. Executes queries + 4. Formats results + """ + schema = load_schema(config['database']) + + tools = [ + QueryExecutor(schema), + SchemaInspector(schema), + ] + + return SQLAgent(llm=llm, tools=tools, schema=schema) +``` + +**Note**: This is intentionally simple to show agentic development from first principles. + +## Troubleshooting + +### ERROR: "Connection refused" +- Is the server running? Check output for port 8001 +- Try: `curl http://localhost:8001/health` + +### ERROR: "Invalid query" +- Teradata connection issue +- Check `.env` credentials +- Verify database access + +### LLM returns empty response +- Check API key in `.env` +- Verify internet connectivity +- Try a simpler query first + +### Slow responses +- Network latency - normal for first query +- Try a provider switch (use LiteLLM) +- Check Teradata performance + +## Performance Tips + +1. **Cache schema** - Agent caches table info after first load +2. **Short queries** - Faster LLM processing +3. **Use GPT-3.5** - Cheaper than GPT-4, still effective + +## Next Steps + +- **[Expanding with Your Agents](/agent-cookbook/running-the-recipes/expanding-agents/)** - Build on this foundation +- **[FAQ](/agent-cookbook/faq/)** - Common questions +- **[GitHub Repository](https://github.com/Teradata/teradata_agent_cookbook)** - Explore the code diff --git a/docs/agent-cookbook/running-the-recipes/environment-setup.md b/docs/agent-cookbook/running-the-recipes/environment-setup.md new file mode 100644 index 0000000000..f4a9974361 --- /dev/null +++ b/docs/agent-cookbook/running-the-recipes/environment-setup.md @@ -0,0 +1,130 @@ +--- +sidebar_position: 2 +--- + +# Environment Setup + +Configure your environment to run Agent Cookbook recipes. + +## Prerequisites + +- **Python 3.10+** - Check with `python --version` +- **Teradata instance** - SQL Engine or VantageCloud Lake +- **LLM API key** - OpenAI, Anthropic, AWS Bedrock, or LiteLLM +- **Git** - For cloning the repository + +## Step 1: Clone and Explore + +```bash +git clone https://github.com/Teradata/teradata_agent_cookbook.git +cd teradata_agent_cookbook + +# Explore the structure +ls recipes/ # See available recipes +ls launcher/ # Launcher utilities +ls ui/ # Web interface +``` + +## Step 2: Create Environment File + +```bash +cp .env.example .env +``` + +Edit `.env` with your configuration: + +```env +# Teradata Connection +TERADATA_HOST=your-instance.teradata.com +TERADATA_USER=your_username +TERADATA_PASSWORD=your_password +TERADATA_DATABASE=your_database + +# LLM Provider (choose one) +OPENAI_API_KEY=sk-... +# OR +ANTHROPIC_API_KEY=sk-ant-... +# OR +AWS_REGION=us-east-1 +AWS_ACCESS_KEY_ID=... +AWS_SECRET_ACCESS_KEY=... + +# Optional: UI Configuration +UI_PORT=5173 +RECIPE_BASE_PORT=8001 +``` + +## Step 3: Install Dependencies + +### Option A: Using uv (Recommended) + +```bash +pip install uv +uv sync +``` + +### Option B: Using pip + +```bash +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate +pip install -r requirements.txt +``` + +## Step 4: Verify Teradata Connection + +```bash +python -c "from shared.connection import get_connection; conn = get_connection(); print('Connected!')" +``` + +**Error? Check**: +- Credentials in `.env` +- Teradata instance is running +- Network connectivity + +## Step 5: Verify LLM Setup + +```bash +python -c "from shared.llm_providers import get_llm_client; client = get_llm_client('openai'); print('LLM configured!')" +``` + +**Error? Check**: +- API key is valid +- Model name is correct +- Provider is accessible + +## Step 6: Run Launcher Setup + +```bash +python launcher.py all --setup +``` + +This: +1. ✅ Creates sample data (teddy_retailers) +2. ✅ Tests all connections +3. ✅ Validates recipe configurations + +## Troubleshooting + +### "AttributeError: module has no attribute..." +- Restart Python interpreter +- Reinstall dependencies: `pip install --upgrade -r requirements.txt` + +### "Connection timeout" +- Verify Teradata hostname +- Check firewall rules +- Test connectivity: `nc -zv host 1025` + +### "API key not found" +- Ensure `.env` file exists +- Check file is in project root +- Reload shell: `source ~/.bashrc` or restart terminal + +### "ModuleNotFoundError" +- Activate virtual environment +- Reinstall: `pip install -r requirements.txt` + +## Next Steps + +- **[Agent Servers and UI](/agent-cookbook/running-the-recipes/agent-servers-ui/)** - Understanding the architecture +- **[Running Data Analyst](/agent-cookbook/running-the-recipes/data-analyst-recipe/)** - Your first agent diff --git a/docs/agent-cookbook/running-the-recipes/expanding-agents.md b/docs/agent-cookbook/running-the-recipes/expanding-agents.md new file mode 100644 index 0000000000..db35f5a66a --- /dev/null +++ b/docs/agent-cookbook/running-the-recipes/expanding-agents.md @@ -0,0 +1,196 @@ +--- +sidebar_position: 5 +--- + +# Expanding with Your Own Agents + +Build on data-analyst to create your custom agents. + +## Starting with Data Analyst + +The data-analyst recipe is intentionally simple, providing: + +- ✅ Proven folder structure +- ✅ Working setup.sql and dependencies +- ✅ Teradata connection pooling +- ✅ LLM client configuration +- ✅ FastAPI server boilerplate + +**Best practice**: Copy and customize rather than build from scratch. + +## Quick Copy-and-Customize + +### Step 1: Copy the Recipe + +```bash +cp -r recipes/basic_agents/data_analyst recipes/basic_agents/my_custom_agent +cd recipes/basic_agents/my_custom_agent +``` + +### Step 2: Update Metadata + +Edit `recipe.yaml`: + +```yaml +name: "My Custom Agent" +description: "My unique agent implementation" +family: "basic-agents" +port: 8008 # Pick a unique port (8001-8007 taken) +llm_providers: ["openai"] +``` + +### Step 3: Add Your Logic + +Edit `agent.py`: + +```python +def create_agent(llm, tools, config): + # Import your custom tools + from my_tools import CustomTool1, CustomTool2 + + # Create tools + tools = [ + CustomTool1(config), + CustomTool2(config), + ] + + # Return your agent + class MyAgent: + def __init__(self, llm, tools): + self.llm = llm + self.tools = tools + + def __call__(self, query): + # Your agent logic + return "Result" + + return MyAgent(llm=llm, tools=tools) +``` + +### Step 4: Add Dependencies + +Edit `pyproject.toml`: + +```toml +dependencies = [ + "fastapi>=0.100.0", + "uvicorn[standard]>=0.24.0", + # Your custom libraries: + "pandas", + "numpy", + "requests", +] +``` + +### Step 5: Test Locally + +```bash +# Server starts automatically on port 8008 +python launcher.py my_custom_agent + +# In another terminal +curl http://localhost:8008/info +curl -X POST http://localhost:8008/invoke \ + -H "Content-Type: application/json" \ + -d '{"query": "test query", "llm": "openai"}' +``` + +### Step 6: See in UI + +```bash +python launcher.py all +``` + +Your new agent appears in the recipe dropdown! + +## Custom Tool Example + +Build a tool that your agent can use: + +```python +# In agent.py +class WebSearchTool: + def __init__(self, config): + self.api_key = config.get('SEARCH_API_KEY') + + def search(self, query): + """Search the web and return results""" + import requests + results = requests.get( + f"https://api.search.com/search?q={query}", + headers={"Authorization": f"Bearer {self.api_key}"} + ) + return results.json()['results'] + + def __call__(self, query): + return self.search(query) +``` + +Then use in agent: + +```python +def create_agent(llm, tools, config): + search_tool = WebSearchTool(config) + + return MyAgent(llm=llm, tools=[search_tool]) +``` + +## Common Customizations + +### 1. Add Database Tools + +```python +def create_agent(llm, tools, config): + from shared.connection import get_connection + + conn = get_connection(config) + + tools = [ + QueryTool(conn), + SchemaTool(conn), + ] + + return Agent(llm=llm, tools=tools) +``` + +### 2. Add External APIs + +```python +def create_agent(llm, tools, config): + tools = [ + WeatherAPI(config), + NewsAPI(config), + TranslationAPI(config), + ] + + return Agent(llm=llm, tools=tools) +``` + +### 3. Add Memory/Context + +```python +def create_agent(llm, tools, config): + memory = ConversationMemory() + + return Agent( + llm=llm, + tools=tools, + memory=memory # Enables multi-turn + ) +``` + +## Publishing Your Recipe + +Ready to share? Contribute back to the cookbook: + +1. **Fork on GitHub** - https://github.com/Teradata/teradata_agent_cookbook +2. **Add your recipe** to `recipes/` with proper structure +3. **Create PR** with documentation +4. **Get reviewed** by maintainers +5. **Merged** into upstream for others to use + +## Next Steps + +- **[FAQ](/agent-cookbook/faq/)** - Troubleshooting and advanced topics +- **[GitHub Repository](https://github.com/Teradata/teradata_agent_cookbook)** - See all recipes +- **[Server Factory Pattern](/agent-cookbook/why-the-cookbook/server-factory/)** - Deep dive on architecture diff --git a/docs/agent-cookbook/running-the-recipes/index.md b/docs/agent-cookbook/running-the-recipes/index.md new file mode 100644 index 0000000000..dddae608a1 --- /dev/null +++ b/docs/agent-cookbook/running-the-recipes/index.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 1 +--- + +# Running the Recipes + +Learn how to set up your environment and run your first agent. + +## Quick Start (5 Minutes) + +```bash +# 1. Clone the repository +git clone https://github.com/Teradata/teradata_agent_cookbook.git +cd teradata_agent_cookbook + +# 2. Set up environment +cp .env.example .env +# Edit .env with your API keys + +# 3. Run the launcher +python launcher.py all --setup + +# 4. Open in browser +open http://localhost:5173 +``` + +## What You'll See + +1. **Launcher starting recipes** - Output shows each agent starting +2. **UI loading** - React interface appears at localhost:5173 +3. **Recipe dropdown** - Select which agent to test +4. **Chat interface** - Ask questions in natural language +5. **Results** - Agent responds with SQL execution and results + +## Available Recipes + +### Basic Agents (Available Now) +- **data-analyst** - SQL query generation and execution + +### Coming Soon +- **data-analyst-multiturn** - Multi-turn conversations +- **data-analyst-dbt** - Schema discovery via DBT +- **data-analyst-mcp** - MCP tool integration +- **governed** - Row-level security +- **vector-search** - Semantic search +- **open-analytics** - Server-side computation + +## Next Steps + +- **[Environment Setup](/agent-cookbook/running-the-recipes/environment-setup/)** - Detailed configuration +- **[Agent Server Architecture](/agent-cookbook/running-the-recipes/agent-servers-ui/)** - How it all works together +- **[Running Data Analyst](/agent-cookbook/running-the-recipes/data-analyst-recipe/)** - Deep dive on first agent +- **[Expanding with Your Agents](/agent-cookbook/running-the-recipes/expanding-agents/)** - Build your own agents diff --git a/docs/agent-cookbook/troubleshooting.md b/docs/agent-cookbook/troubleshooting.md new file mode 100644 index 0000000000..49638d8652 --- /dev/null +++ b/docs/agent-cookbook/troubleshooting.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 6 +--- + +# Troubleshooting + +Common issues and solutions for agent development and deployment. + +This section will contain: +- Common issues +- Debugging techniques +- Performance issues +- FAQ diff --git a/docs/agent-cookbook/why-the-cookbook/index.md b/docs/agent-cookbook/why-the-cookbook/index.md new file mode 100644 index 0000000000..4ae1cdcc12 --- /dev/null +++ b/docs/agent-cookbook/why-the-cookbook/index.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 1 +--- + +# Why the Cookbook + +Agent Cookbook brings a proven production-ready approach to building intelligent agents with Teradata. + +## The Journey: From Notebooks to Production + +For years, data scientists have built amazing agent recipes in Jupyter notebooks inside Clearscape Analytics. These notebooks are excellent for learning and experimentation, but they face a critical challenge: **they don't run in production**. + +Agent Cookbook solves this by providing: + +- **Server-based agents** - Deploy your agent logic as a FastAPI server +- **Uniform interfaces** - Every agent has the same endpoints across recipes +- **UI integration** - Test and explore agents through a web interface +- **Scalable architecture** - Built on proven patterns, ready for enterprise + +As Daniel explains in the introduction: + +> "What we are bringing to you is an easy way to move from notebook implementations to how you will implement agents in production with actual servers that are serving those agents to a UI." + +## The Vision + +The Cookbook provides recipes you can: +1. **Learn from** - Understand how production agents work +2. **Build upon** - Extend with your own tools and logic +3. **Deploy** - Ship as real API services +4. **Combine** - Chain multiple agents together + +## What's Inside + +**Today**: Basic agents for SQL analysis +- `data-analyst` - Single-turn SQL query agent + +**Soon**: +- `data-analyst-multiturn` - With conversation memory +- `data-analyst-dbt` - Schema discovery via DBT integration +- `data-analyst-mcp` - Dynamic tool discovery via MCP +- `governed` - Row-level security +- `vector-search` - Semantic search +- `open-analytics` - Server-side computation +- Enterprise patterns with advanced capabilities + +## Repository + +Explore the complete source on GitHub: +[Teradata Agent Cookbook](https://github.com/Teradata/teradata_agent_cookbook) + +## Next Steps + +- **[Repository Structure](/agent-cookbook/why-the-cookbook/repository-structure/)** - How the Cookbook is organized +- **[Server Factory Pattern](/agent-cookbook/why-the-cookbook/server-factory/)** - The architecture behind uniform APIs +- **[LLM Providers](/agent-cookbook/why-the-cookbook/llm-providers/)** - Choose your language model +- **[Running the Recipes](/agent-cookbook/running-the-recipes/)** - Get started with your first agent diff --git a/docs/agent-cookbook/why-the-cookbook/llm-providers.md b/docs/agent-cookbook/why-the-cookbook/llm-providers.md new file mode 100644 index 0000000000..6e065c4f0d --- /dev/null +++ b/docs/agent-cookbook/why-the-cookbook/llm-providers.md @@ -0,0 +1,145 @@ +--- +sidebar_position: 4 +--- + +# LLM Providers + +Agent Cookbook supports multiple language models. Choose the one that fits your needs. + +## Supported Providers + +### OpenAI +- **Models**: GPT-3.5 Turbo, GPT-4, GPT-4 Turbo +- **Cost**: Medium ($0.002-$0.03 per 1K tokens) +- **Speed**: Fast +- **Best for**: Production use, high accuracy + +**Setup**: +```bash +export OPENAI_API_KEY="sk-..." +``` + +### Anthropic +- **Models**: Claude 3 Opus, Sonnet, Haiku +- **Cost**: Medium ($0.003-$0.02 per 1K tokens) +- **Speed**: Medium +- **Best for**: Reasoning-heavy tasks + +**Setup**: +```bash +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +### AWS Bedrock +- **Models**: Claude, Llama, Mistral +- **Cost**: Low ($0.0008-$0.004 per 1K tokens) +- **Speed**: Medium +- **Best for**: AWS deployments, cost-sensitive + +**Setup**: +```bash +export AWS_REGION="us-east-1" +export AWS_ACCESS_KEY_ID="..." +export AWS_SECRET_ACCESS_KEY="..." +``` + +### LiteLLM (Recommended for Learning) +- **Models**: All of the above via proxy +- **Cost**: Lowest (direct provider pricing) +- **Speed**: Depends on underlying model +- **Best for**: Testing, cost optimization, model comparison + +**Setup**: +```bash +export LITELLM_MASTER_KEY="your-key" +# Or use provider keys (OpenAI, Anthropic, etc.) +export OPENAI_API_KEY="sk-..." +``` + +## Comparison Matrix + +| Feature | OpenAI | Anthropic | Bedrock | LiteLLM | +|---------|--------|-----------|---------|---------| +| Easy to start | ✅ | ✅ | Complex | ✅ | +| Multiple models | Limited | Limited | Full | Full | +| Cost control | Medium | Medium | High | Best | +| Self-hosted | ❌ | ❌ | ❌ | ✅ | +| Fallback support | ❌ | ❌ | ❌ | ✅ | + +## Switching Providers + +Recipes support switching providers via recipe.yaml: + +```yaml +llm_providers: + - openai + - anthropic + - bedrock + - litellm +``` + +At runtime, specify which to use: + +```bash +# Use OpenAI +python launcher.py data-analyst --llm openai + +# Use Anthropic +python launcher.py data-analyst --llm anthropic + +# Use LiteLLM (proxy to your choice) +python launcher.py data-analyst --llm litellm +``` + +## Best Practices + +1. **Start with LiteLLM** - Lowest barrier to entry +2. **Test with GPT-3.5** - Fast and cheap +3. **Use Claude for reasoning** - Better at complex logic +4. **Switch to GPT-4 for accuracy** - When results matter +5. **Consider Bedrock** - If already on AWS + +## Configuration + +All providers use environment variables. Create a `.env` file: + +```env +# OpenAI +OPENAI_API_KEY=sk-... + +# Anthropic +ANTHROPIC_API_KEY=sk-ant-... + +# AWS Bedrock +AWS_REGION=us-east-1 +AWS_ACCESS_KEY_ID=... +AWS_SECRET_ACCESS_KEY=... +``` + +Load via launcher: +```bash +source .env +python launcher.py all +``` + +## Troubleshooting + +**"Model not found" error** +- Verify model name matches provider (e.g., `gpt-3.5-turbo` not `gpt-35`) +- Check API key is valid +- Ensure model is available in your region + +**High costs** +- Switch to LiteLLM or Bedrock +- Use GPT-3.5 instead of GPT-4 +- Cache prompts when possible + +**Slow responses** +- Check provider status pages +- Try a different provider +- Reduce prompt size + +## Next Steps + +- **[Running the Recipes](/agent-cookbook/running-the-recipes/)** - Try your first agent +- **[FAQ](/agent-cookbook/faq/)** - More provider questions diff --git a/docs/agent-cookbook/why-the-cookbook/repository-structure.md b/docs/agent-cookbook/why-the-cookbook/repository-structure.md new file mode 100644 index 0000000000..63f083b4a9 --- /dev/null +++ b/docs/agent-cookbook/why-the-cookbook/repository-structure.md @@ -0,0 +1,110 @@ +--- +sidebar_position: 2 +--- + +# Repository Structure + +Understanding how Agent Cookbook is organized helps you navigate and extend it. + +## Top-Level Directories + +``` +teradata_agent_cookbook/ +├── recipes/ # Recipe implementations +├── launcher/ # Orchestration tool +├── shared/ # Shared utilities +├── ui/ # React web interface +└── docs/ # Documentation +``` + +## `recipes/` - The Heart of the Cookbook + +This is where agent implementations live: + +``` +recipes/ +├── basic_agents/ # Foundation agents +│ └── data_analyst/ # SQL query agent +├── enterprise/ # Production-grade agents (coming soon) +│ ├── governed/ # With row-level security +│ ├── vector_search/ # Semantic search +│ └── open_analytics/ # Server-side computation +└── advanced/ # Advanced patterns (coming soon) +``` + +### Recipe Structure + +Each recipe follows the same pattern: + +``` +data_analyst/ +├── recipe.yaml # Metadata (name, port, LLM providers) +├── server.py # FastAPI entry point (boilerplate) +├── agent.py # Your agent logic +├── pyproject.toml # Python dependencies +├── uv.lock # Locked dependencies +├── setup.sql # Data initialization +└── README.md # Recipe-specific docs +``` + +## `launcher/` - Orchestration + +The launcher simplifies running recipes: + +``` +launcher/ +├── launcher.py # Main entry point +├── config/ # Configuration management +├── metadata.py # Recipe discovery +└── server_manager.py # Process management +``` + +### Launcher Features + +- **Discovery**: Automatically finds all recipes +- **Startup**: Initializes services in correct order +- **Port Management**: Assigns ports from configuration +- **UI Launch**: Starts the React interface + +**Example**: `python launcher.py all` starts everything. + +## `shared/` - Shared Utilities + +Common code reused by recipes: + +``` +shared/ +├── connection.py # Teradata connection pooling +├── config.py # Configuration loading +├── llm_providers.py # LLM client factories +├── auth.py # Authentication helpers +└── logging.py # Unified logging +``` + +## `ui/` - Web Interface + +React application for testing recipes: + +``` +ui/ +├── src/ +│ ├── components/ # UI components +│ ├── pages/ # Page layouts +│ ├── services/ # API clients +│ └── App.js +└── package.json # Dependencies +``` + +**Port**: 5173 (default) + +## File Organization Principles + +1. **Modularity** - Each recipe is independent +2. **Reusability** - Shared code in `shared/` +3. **Configuration** - Settings in `recipe.yaml` and `.env` +4. **Simplicity** - Minimal boilerplate in `server.py` + +## Next Steps + +- **[Server Factory Pattern](/agent-cookbook/why-the-cookbook/server-factory/)** - Learn the architecture +- **[Running the Recipes](/agent-cookbook/running-the-recipes/)** - Get your first agent running diff --git a/docs/agent-cookbook/why-the-cookbook/server-factory.md b/docs/agent-cookbook/why-the-cookbook/server-factory.md new file mode 100644 index 0000000000..d52c386c56 --- /dev/null +++ b/docs/agent-cookbook/why-the-cookbook/server-factory.md @@ -0,0 +1,157 @@ +--- +sidebar_position: 3 +--- + +# Server Factory Pattern + +The server factory is the hidden gem that makes Agent Cookbook production-ready. + +## The Problem + +Building a production API for each agent would require: + +- Middleware setup (authentication, logging, error handling) +- Endpoint boilerplate (info, invoke, health checks) +- Configuration loading (environment variables, secrets) +- Repeatability (copy-paste across all recipes) + +This leads to **code duplication** and **maintenance burden**. + +## The Solution: Server Factory + +As Daniel explains: + +> "The hidden parts of agentic development was the server configuration. That is the one that you can derive the most value from our recipes." + +The server factory is a Python module that generates FastAPI apps with all the infrastructure: + +```python +# In server.py (just 3 lines!) +from server_factory import create_app +from agent import create_agent + +app = create_app(recipe_path=__file__, agent_factory=create_agent) +``` + +That's it. Everything else is handled. + +## What the Factory Provides + +### 1. **Uniform Endpoints** + +Every recipe exposes the same API: + +``` +GET /info + Response: { "name", "description", "llm_providers", "port" } + +POST /invoke + Body: { "query": "Your question", "llm": "openai", ... } + Response: { "result", "reasoning", "tokens_used" } + +GET /health + Response: { "status": "healthy" } +``` + +### 2. **Configuration Loading** + +Automatically reads from: +- `recipe.yaml` - Recipe metadata +- `.env` - LLM keys, Teradata credentials +- Environment variables + +### 3. **Middleware Stack** + +- **Logging**: All requests logged with structured output +- **Error Handling**: Graceful error responses +- **Authentication**: Optional API key validation +- **CORS**: Cross-origin requests allowed for UI + +### 4. **Standardized Response Format** + +All responses follow the same structure: + +```json +{ + "status": "success", + "data": { + "result": "Agent response here", + "metadata": { + "llm_model": "gpt-3.5-turbo", + "tokens_used": 127, + "execution_time_ms": 340 + } + } +} +``` + +## Agent Integration + +Your agent defines the interface: + +```python +def create_agent(llm, tools, config): + """ + Factory function that creates your agent. + + Args: + llm: LLM client (automatically instantiated) + tools: Tools available to the agent + config: Configuration from recipe.yaml + .env + + Returns: + Your agent instance with a __call__ method + """ + return MyAgent(llm=llm, tools=tools, ...) +``` + +The factory: +1. Introspects the agent's signature +2. Builds matching FastAPI endpoints +3. Calls the agent with the right parameters +4. Returns standardized responses + +## Benefits + +| Aspect | Traditional | Factory | +|--------|-----------|---------| +| **Lines of code** | 200-500 | ~50 | +| **Setup time** | 2-3 hours | 15 minutes | +| **Debugging** | Per-recipe | Centralized | +| **API consistency** | Manual | Automatic | +| **Adding middleware** | Edit all recipes | Edit factory once | + +## Architecture Diagram + +``` +┌─────────────────────────────────────┐ +│ Browser / UI │ +│ (localhost:5173) │ +└─────────────────────────────────────┘ + ↓ POST /invoke +┌─────────────────────────────────────┐ +│ FastAPI Server (Port 8001) │ +│ ┌─────────────────────────────────┐│ +│ │ Server Factory (created) ││ +│ │ - Routing ││ +│ │ - Middleware ││ +│ │ - Error Handling ││ +│ └─────────────────────────────────┘│ +│ ┌─────────────────────────────────┐│ +│ │ Your Agent (recipe-specific) ││ +│ │ - LLM interaction ││ +│ │ - Tool execution ││ +│ │ - Business logic ││ +│ └─────────────────────────────────┘│ +└─────────────────────────────────────┘ + ↓ Query +┌─────────────────────────────────────┐ +│ Teradata database │ +│ (via connection pool) │ +└─────────────────────────────────────┘ +``` + +## Next Steps + +- **[LLM Providers](/agent-cookbook/why-the-cookbook/llm-providers/)** - Configure your language model +- **[Running the Recipes](/agent-cookbook/running-the-recipes/)** - See it in action diff --git a/docs/FAQ.md b/docs/ai-unlimited/FAQ.md similarity index 100% rename from docs/FAQ.md rename to docs/ai-unlimited/FAQ.md diff --git a/docs/_partials/_clone-repo.mdx b/docs/ai-unlimited/_partials/_clone-repo.mdx similarity index 100% rename from docs/_partials/_clone-repo.mdx rename to docs/ai-unlimited/_partials/_clone-repo.mdx diff --git a/docs/explore-and-analyze-data/collab.svg b/docs/ai-unlimited/explore-and-analyze-data/collab.svg similarity index 100% rename from docs/explore-and-analyze-data/collab.svg rename to docs/ai-unlimited/explore-and-analyze-data/collab.svg diff --git a/docs/explore-and-analyze-data/collaborate-project.md b/docs/ai-unlimited/explore-and-analyze-data/collaborate-project.md similarity index 100% rename from docs/explore-and-analyze-data/collaborate-project.md rename to docs/ai-unlimited/explore-and-analyze-data/collaborate-project.md diff --git a/docs/explore-and-analyze-data/create-first-project.md b/docs/ai-unlimited/explore-and-analyze-data/create-first-project.md similarity index 100% rename from docs/explore-and-analyze-data/create-first-project.md rename to docs/ai-unlimited/explore-and-analyze-data/create-first-project.md diff --git a/docs/explore-and-analyze-data/example-projects.md b/docs/ai-unlimited/explore-and-analyze-data/example-projects.md similarity index 100% rename from docs/explore-and-analyze-data/example-projects.md rename to docs/ai-unlimited/explore-and-analyze-data/example-projects.md diff --git a/docs/explore-and-analyze-data/get-api-key.md b/docs/ai-unlimited/explore-and-analyze-data/get-api-key.md similarity index 100% rename from docs/explore-and-analyze-data/get-api-key.md rename to docs/ai-unlimited/explore-and-analyze-data/get-api-key.md diff --git a/docs/explore-and-analyze-data/index.md b/docs/ai-unlimited/explore-and-analyze-data/index.md similarity index 100% rename from docs/explore-and-analyze-data/index.md rename to docs/ai-unlimited/explore-and-analyze-data/index.md diff --git a/docs/explore-and-analyze-data/magic-commands.md b/docs/ai-unlimited/explore-and-analyze-data/magic-commands.md similarity index 100% rename from docs/explore-and-analyze-data/magic-commands.md rename to docs/ai-unlimited/explore-and-analyze-data/magic-commands.md diff --git a/docs/explore-and-analyze-data/owner.svg b/docs/ai-unlimited/explore-and-analyze-data/owner.svg similarity index 100% rename from docs/explore-and-analyze-data/owner.svg rename to docs/ai-unlimited/explore-and-analyze-data/owner.svg diff --git a/docs/explore-and-analyze-data/project-flow.md b/docs/ai-unlimited/explore-and-analyze-data/project-flow.md similarity index 100% rename from docs/explore-and-analyze-data/project-flow.md rename to docs/ai-unlimited/explore-and-analyze-data/project-flow.md diff --git a/docs/fabric/cell-sum.svg b/docs/ai-unlimited/fabric/cell-sum.svg similarity index 100% rename from docs/fabric/cell-sum.svg rename to docs/ai-unlimited/fabric/cell-sum.svg diff --git a/docs/fabric/close-nb.svg b/docs/ai-unlimited/fabric/close-nb.svg similarity index 100% rename from docs/fabric/close-nb.svg rename to docs/ai-unlimited/fabric/close-nb.svg diff --git a/docs/fabric/disconnect.svg b/docs/ai-unlimited/fabric/disconnect.svg similarity index 100% rename from docs/fabric/disconnect.svg rename to docs/ai-unlimited/fabric/disconnect.svg diff --git a/docs/fabric/drag-data.svg b/docs/ai-unlimited/fabric/drag-data.svg similarity index 100% rename from docs/fabric/drag-data.svg rename to docs/ai-unlimited/fabric/drag-data.svg diff --git a/docs/fabric/first-use-case.md b/docs/ai-unlimited/fabric/first-use-case.md similarity index 100% rename from docs/fabric/first-use-case.md rename to docs/ai-unlimited/fabric/first-use-case.md diff --git a/docs/fabric/get-started/browse-lakehouse.svg b/docs/ai-unlimited/fabric/get-started/browse-lakehouse.svg similarity index 100% rename from docs/fabric/get-started/browse-lakehouse.svg rename to docs/ai-unlimited/fabric/get-started/browse-lakehouse.svg diff --git a/docs/fabric/get-started/connect-lakehouse.md b/docs/ai-unlimited/fabric/get-started/connect-lakehouse.md similarity index 100% rename from docs/fabric/get-started/connect-lakehouse.md rename to docs/ai-unlimited/fabric/get-started/connect-lakehouse.md diff --git a/docs/fabric/get-started/connect-lakehouse.svg b/docs/ai-unlimited/fabric/get-started/connect-lakehouse.svg similarity index 100% rename from docs/fabric/get-started/connect-lakehouse.svg rename to docs/ai-unlimited/fabric/get-started/connect-lakehouse.svg diff --git a/docs/fabric/get-started/create-lakehouse.svg b/docs/ai-unlimited/fabric/get-started/create-lakehouse.svg similarity index 100% rename from docs/fabric/get-started/create-lakehouse.svg rename to docs/ai-unlimited/fabric/get-started/create-lakehouse.svg diff --git a/docs/fabric/get-started/create-notebook.md b/docs/ai-unlimited/fabric/get-started/create-notebook.md similarity index 100% rename from docs/fabric/get-started/create-notebook.md rename to docs/ai-unlimited/fabric/get-started/create-notebook.md diff --git a/docs/fabric/get-started/create-notebook.svg b/docs/ai-unlimited/fabric/get-started/create-notebook.svg similarity index 100% rename from docs/fabric/get-started/create-notebook.svg rename to docs/ai-unlimited/fabric/get-started/create-notebook.svg diff --git a/docs/fabric/get-started/create-sample.svg b/docs/ai-unlimited/fabric/get-started/create-sample.svg similarity index 100% rename from docs/fabric/get-started/create-sample.svg rename to docs/ai-unlimited/fabric/get-started/create-sample.svg diff --git a/docs/fabric/get-started/data-preparation.svg b/docs/ai-unlimited/fabric/get-started/data-preparation.svg similarity index 100% rename from docs/fabric/get-started/data-preparation.svg rename to docs/ai-unlimited/fabric/get-started/data-preparation.svg diff --git a/docs/fabric/get-started/index.md b/docs/ai-unlimited/fabric/get-started/index.md similarity index 100% rename from docs/fabric/get-started/index.md rename to docs/ai-unlimited/fabric/get-started/index.md diff --git a/docs/fabric/get-started/load-data.md b/docs/ai-unlimited/fabric/get-started/load-data.md similarity index 100% rename from docs/fabric/get-started/load-data.md rename to docs/ai-unlimited/fabric/get-started/load-data.md diff --git a/docs/fabric/get-started/sample-data.svg b/docs/ai-unlimited/fabric/get-started/sample-data.svg similarity index 100% rename from docs/fabric/get-started/sample-data.svg rename to docs/ai-unlimited/fabric/get-started/sample-data.svg diff --git a/docs/fabric/get-started/top-cell.svg b/docs/ai-unlimited/fabric/get-started/top-cell.svg similarity index 100% rename from docs/fabric/get-started/top-cell.svg rename to docs/ai-unlimited/fabric/get-started/top-cell.svg diff --git a/docs/fabric/get-started/workload-hub.svg b/docs/ai-unlimited/fabric/get-started/workload-hub.svg similarity index 100% rename from docs/fabric/get-started/workload-hub.svg rename to docs/ai-unlimited/fabric/get-started/workload-hub.svg diff --git a/docs/fabric/in-db-functions.md b/docs/ai-unlimited/fabric/in-db-functions.md similarity index 100% rename from docs/fabric/in-db-functions.md rename to docs/ai-unlimited/fabric/in-db-functions.md diff --git a/docs/fabric/new-cell.svg b/docs/ai-unlimited/fabric/new-cell.svg similarity index 100% rename from docs/fabric/new-cell.svg rename to docs/ai-unlimited/fabric/new-cell.svg diff --git a/docs/fabric/new-table.svg b/docs/ai-unlimited/fabric/new-table.svg similarity index 100% rename from docs/fabric/new-table.svg rename to docs/ai-unlimited/fabric/new-table.svg diff --git a/docs/fabric/save-work.svg b/docs/ai-unlimited/fabric/save-work.svg similarity index 100% rename from docs/fabric/save-work.svg rename to docs/ai-unlimited/fabric/save-work.svg diff --git a/docs/fabric/section2-1.svg b/docs/ai-unlimited/fabric/section2-1.svg similarity index 100% rename from docs/fabric/section2-1.svg rename to docs/ai-unlimited/fabric/section2-1.svg diff --git a/docs/glossary.md b/docs/ai-unlimited/glossary.md similarity index 100% rename from docs/glossary.md rename to docs/ai-unlimited/glossary.md diff --git a/docs/install-ai-unlimited/index.md b/docs/ai-unlimited/install-ai-unlimited/index.md similarity index 100% rename from docs/install-ai-unlimited/index.md rename to docs/ai-unlimited/install-ai-unlimited/index.md diff --git a/docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md b/docs/ai-unlimited/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md similarity index 100% rename from docs/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md rename to docs/ai-unlimited/install-ai-unlimited/prod-aws-console-deploy-ai-unlimited.md diff --git a/docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md b/docs/ai-unlimited/install-ai-unlimited/prod-azure-portal-deploy-manager.md similarity index 100% rename from docs/install-ai-unlimited/prod-azure-portal-deploy-manager.md rename to docs/ai-unlimited/install-ai-unlimited/prod-azure-portal-deploy-manager.md diff --git a/docs/install-ai-unlimited/setup-ai-unlimited.md b/docs/ai-unlimited/install-ai-unlimited/setup-ai-unlimited.md similarity index 100% rename from docs/install-ai-unlimited/setup-ai-unlimited.md rename to docs/ai-unlimited/install-ai-unlimited/setup-ai-unlimited.md diff --git a/docs/manage-ai-unlimited/add-collaborators.md b/docs/ai-unlimited/manage-ai-unlimited/add-collaborators.md similarity index 100% rename from docs/manage-ai-unlimited/add-collaborators.md rename to docs/ai-unlimited/manage-ai-unlimited/add-collaborators.md diff --git a/docs/manage-ai-unlimited/change-settings.md b/docs/ai-unlimited/manage-ai-unlimited/change-settings.md similarity index 100% rename from docs/manage-ai-unlimited/change-settings.md rename to docs/ai-unlimited/manage-ai-unlimited/change-settings.md diff --git a/docs/manage-ai-unlimited/index.md b/docs/ai-unlimited/manage-ai-unlimited/index.md similarity index 100% rename from docs/manage-ai-unlimited/index.md rename to docs/ai-unlimited/manage-ai-unlimited/index.md diff --git a/docs/manage-ai-unlimited/suspend-and-restore-project.md b/docs/ai-unlimited/manage-ai-unlimited/suspend-and-restore-project.md similarity index 100% rename from docs/manage-ai-unlimited/suspend-and-restore-project.md rename to docs/ai-unlimited/manage-ai-unlimited/suspend-and-restore-project.md diff --git a/docs/resources/aws-requirements.md b/docs/ai-unlimited/resources/aws-requirements.md similarity index 100% rename from docs/resources/aws-requirements.md rename to docs/ai-unlimited/resources/aws-requirements.md diff --git a/docs/resources/azure-requirements.md b/docs/ai-unlimited/resources/azure-requirements.md similarity index 100% rename from docs/resources/azure-requirements.md rename to docs/ai-unlimited/resources/azure-requirements.md diff --git a/docs/resources/create-oauth-app.md b/docs/ai-unlimited/resources/create-oauth-app.md similarity index 100% rename from docs/resources/create-oauth-app.md rename to docs/ai-unlimited/resources/create-oauth-app.md diff --git a/docs/resources/index.md b/docs/ai-unlimited/resources/index.md similarity index 100% rename from docs/resources/index.md rename to docs/ai-unlimited/resources/index.md diff --git a/docs/resources/jupyterlab/index.md b/docs/ai-unlimited/resources/jupyterlab/index.md similarity index 100% rename from docs/resources/jupyterlab/index.md rename to docs/ai-unlimited/resources/jupyterlab/index.md diff --git a/docs/resources/jupyterlab/install-jupyterlab-aws.md b/docs/ai-unlimited/resources/jupyterlab/install-jupyterlab-aws.md similarity index 100% rename from docs/resources/jupyterlab/install-jupyterlab-aws.md rename to docs/ai-unlimited/resources/jupyterlab/install-jupyterlab-aws.md diff --git a/docs/resources/jupyterlab/install-jupyterlab-azure.md b/docs/ai-unlimited/resources/jupyterlab/install-jupyterlab-azure.md similarity index 100% rename from docs/resources/jupyterlab/install-jupyterlab-azure.md rename to docs/ai-unlimited/resources/jupyterlab/install-jupyterlab-azure.md diff --git a/docs/resources/jupyterlab/run-jupyterlab-docker.md b/docs/ai-unlimited/resources/jupyterlab/run-jupyterlab-docker.md similarity index 100% rename from docs/resources/jupyterlab/run-jupyterlab-docker.md rename to docs/ai-unlimited/resources/jupyterlab/run-jupyterlab-docker.md diff --git a/docs/resources/quickstart/docker-install-ai-unlimited-jupyter.md b/docs/ai-unlimited/resources/quickstart/docker-install-ai-unlimited-jupyter.md similarity index 100% rename from docs/resources/quickstart/docker-install-ai-unlimited-jupyter.md rename to docs/ai-unlimited/resources/quickstart/docker-install-ai-unlimited-jupyter.md diff --git a/docs/resources/quickstart/docker-when-you-are-done.md b/docs/ai-unlimited/resources/quickstart/docker-when-you-are-done.md similarity index 100% rename from docs/resources/quickstart/docker-when-you-are-done.md rename to docs/ai-unlimited/resources/quickstart/docker-when-you-are-done.md diff --git a/docs/resources/quickstart/index.md b/docs/ai-unlimited/resources/quickstart/index.md similarity index 100% rename from docs/resources/quickstart/index.md rename to docs/ai-unlimited/resources/quickstart/index.md diff --git a/docs/support.md b/docs/ai-unlimited/support.md similarity index 100% rename from docs/support.md rename to docs/ai-unlimited/support.md diff --git a/docs/whats-new/index.md b/docs/ai-unlimited/whats-new/index.md similarity index 100% rename from docs/whats-new/index.md rename to docs/ai-unlimited/whats-new/index.md diff --git a/docs/whats-new/release-notes.md b/docs/ai-unlimited/whats-new/release-notes.md similarity index 100% rename from docs/whats-new/release-notes.md rename to docs/ai-unlimited/whats-new/release-notes.md diff --git a/docusaurus.config.js b/docusaurus.config.js index c468061294..9b53d98f3c 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -103,6 +103,16 @@ const config = { plugins: [ tailwindPlugin, + [ + '@docusaurus/plugin-content-docs', + { + id: 'ai-unlimited', + path: 'docs/ai-unlimited', + routeBasePath: 'ai-unlimited', + sidebarPath: './sidebars/ai-unlimited.js', + sidebarItemsGenerator, + }, + ], [ '@docusaurus/plugin-content-blog', { @@ -131,6 +141,15 @@ const config = { sidebarPath: './sidebars.js', }, ], + [ + '@docusaurus/plugin-content-docs', + { + id: 'agent-cookbook', + path: 'docs/agent-cookbook', + routeBasePath: 'agent-cookbook', + sidebarPath: './sidebars/agent-cookbook.js', + }, + ], './plugins/gtm-plugin', ], @@ -139,13 +158,7 @@ const config = { 'classic', /** @type {import('@docusaurus/preset-classic').Options} */ ({ - docs: { - // Use a custom sidebar generator which is built on top of the default generator - sidebarItemsGenerator, - routeBasePath: 'ai-unlimited', - path: 'docs', - sidebarPath: './sidebars.js', - }, + docs: false, blog: { showReadingTime: true, // Please change this to your repo. diff --git a/i18n/en/code.json b/i18n/en/code.json index a79b3ea8eb..cd88e0a094 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -677,5 +677,11 @@ }, "quickstarts.open_table_formats_decription": { "message": "How to set up, query, and update Apache Iceberg and Delta Lake Open Table Format tables." + }, + "agent_cookbook.getting_started": { + "message": "Getting Started" + }, + "agent_cookbook.recipes": { + "message": "Recipes" } } diff --git a/sidebars/agent-cookbook.js b/sidebars/agent-cookbook.js new file mode 100644 index 0000000000..83f060073f --- /dev/null +++ b/sidebars/agent-cookbook.js @@ -0,0 +1,31 @@ +/** + * Sidebar for Agent Cookbook documentation + * Three main sections: Why the Cookbook, Running the Recipes, FAQ + */ + +// @ts-check + +/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ +const sidebars = { + agentCookbookMain: [ + { + type: 'category', + label: 'Why the Cookbook', + collapsed: false, + items: [ + { type: 'autogenerated', dirName: 'why-the-cookbook' }, + ], + }, + { + type: 'category', + label: 'Running the Recipes', + collapsed: false, + items: [ + { type: 'autogenerated', dirName: 'running-the-recipes' }, + ], + }, + 'faq', + ], +}; + +export default sidebars; diff --git a/sidebars/ai-unlimited.js b/sidebars/ai-unlimited.js new file mode 100644 index 0000000000..fd47c94671 --- /dev/null +++ b/sidebars/ai-unlimited.js @@ -0,0 +1,20 @@ +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of each product + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + */ + +// @ts-check + +/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ +const sidebars = { + // AI Unlimited main sidebar - auto-generated from root of ai-unlimited docs + tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }], + // Fabric-specific sidebar + fabricSidebar: [{ type: 'autogenerated', dirName: 'fabric' }], +}; + +export default sidebars; diff --git a/src/components/AgentCookbookFeatures/AgentCookbookEditions.js b/src/components/AgentCookbookFeatures/AgentCookbookEditions.js new file mode 100644 index 0000000000..2e5117e732 --- /dev/null +++ b/src/components/AgentCookbookFeatures/AgentCookbookEditions.js @@ -0,0 +1,19 @@ +import React from 'react'; +import { TabBar, Tab } from '@teradata-web/react-components'; +import { translate } from '@docusaurus/Translate'; +import GettingStarted from './GettingStarted'; +import Recipes from './Recipes'; + +export default function AgentCookbookEditions() { + return ( + + + + + + + + + + ); +} diff --git a/src/components/AgentCookbookFeatures/GettingStarted.js b/src/components/AgentCookbookFeatures/GettingStarted.js new file mode 100644 index 0000000000..6233c865e9 --- /dev/null +++ b/src/components/AgentCookbookFeatures/GettingStarted.js @@ -0,0 +1,48 @@ +import clsx from 'clsx'; +import Heading from '@theme/Heading'; +import styles from '../HomepageFeatures/styles.module.css'; +import Link from '@docusaurus/Link'; +import { Typography } from '@teradata-web/react-components'; + +const FeatureList = [ + { + title: 'Why the Cookbook', + description: 'Understand the vision: moving from notebooks to production. Learn the repository structure, server factory pattern, and LLM providers.', + href: '/agent-cookbook/why-the-cookbook/', + }, + { + title: 'Running the Recipes', + description: 'Environment setup, agent server architecture, run the data analyst recipe, and expand with your own agents.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + title: 'FAQ', + description: 'Common questions, troubleshooting, architecture deep dives, and quick reference answers.', + href: '/agent-cookbook/faq/', + }, +]; + +function Feature({ title, description, href }) { + return ( + +
+ {title} + {description &&

{description}

} +
+ + ); +} + +export default function GettingStarted() { + return ( +
+
+
+ {FeatureList.map((props, idx) => ( + + ))} +
+
+
+ ); +} diff --git a/src/components/AgentCookbookFeatures/Recipes.js b/src/components/AgentCookbookFeatures/Recipes.js new file mode 100644 index 0000000000..63baef5b16 --- /dev/null +++ b/src/components/AgentCookbookFeatures/Recipes.js @@ -0,0 +1,109 @@ +import clsx from 'clsx'; +import Heading from '@theme/Heading'; +import styles from '../HomepageFeatures/styles.module.css'; +import Link from '@docusaurus/Link'; + +const RecipesList = [ + { + name: 'Data Analyst', + status: 'Available', + port: '8001', + description: 'SQL generation and data analysis agent for interactive multi-turn queries.', + href: '/agent-cookbook/running-the-recipes/data-analyst-recipe/', + }, + { + name: 'Multi-Turn Agent', + status: 'Coming Soon', + port: '8002', + description: 'Extended data analyst with conversation memory and stateful interactions.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + name: 'DBT Integration', + status: 'Coming Soon', + port: '8003', + description: 'Data build tool integration for pipeline orchestration and testing.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + name: 'Model Context Protocol', + status: 'Coming Soon', + port: '8004', + description: 'MCP servers for standardized tool and resource integration.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + name: 'Governed Analytics', + status: 'Coming Soon', + port: '8005', + description: 'Role-based access control and audit logging for enterprise deployments.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + name: 'Vector Search', + status: 'Coming Soon', + port: '8006', + description: 'Semantic search and RAG patterns for knowledge retrieval.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + name: 'Open Analytics', + status: 'Coming Soon', + port: '8007', + description: 'Extensible recipe framework for custom agent builders.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + name: 'Enterprise Patterns', + status: 'Coming Soon', + port: '8008', + description: 'Production-ready patterns for scaling agents across organizations.', + href: '/agent-cookbook/running-the-recipes/', + }, +]; + +function RecipeCard({ name, status, port, description, href }) { + const isAvailable = status === 'Available'; + const statusColor = isAvailable ? '#4CAF50' : '#FF9800'; + + return ( + +
+
+ + {name} + + + {status} + +
+

+ Port: {port} +

+

{description}

+
+ + ); +} + +export default function Recipes() { + return ( +
+
+
+ {RecipesList.map((props, idx) => ( + + ))} +
+
+
+ ); +} diff --git a/src/components/AgentCookbookFeatures/index.js b/src/components/AgentCookbookFeatures/index.js new file mode 100644 index 0000000000..0c1e38ce33 --- /dev/null +++ b/src/components/AgentCookbookFeatures/index.js @@ -0,0 +1,61 @@ +import clsx from 'clsx'; +import Heading from '@theme/Heading'; +import Link from '@docusaurus/Link'; +import { Typography } from '@teradata-web/react-components'; +import styles from '../HomepageFeatures/styles.module.css'; + +const FeatureList = [ + { + title: 'Why the Cookbook', + description: 'Understand the vision: moving from notebooks to production. Learn the repository structure, server factory pattern, and LLM providers.', + href: '/agent-cookbook/why-the-cookbook/', + }, + { + title: 'Running the Recipes', + description: 'Environment setup, agent server architecture, run the data analyst recipe, and expand with your own agents.', + href: '/agent-cookbook/running-the-recipes/', + }, + { + title: 'FAQ', + description: 'Common questions, troubleshooting, architecture deep dives, and quick reference answers.', + href: '/agent-cookbook/faq/', + }, +]; + +function Feature({ title, description, href }) { + return ( + +
+ {title} + {description &&

{description}

} +
+ + ); +} + +export default function AgentCookbookFeatures() { + return ( +
+
+
+
+ + Explore Agent Recipes + + +

+ + Start Building Your Agent + +

+
+
+
+ {FeatureList.map((props, idx) => ( + + ))} +
+
+
+ ); +} diff --git a/src/config/header.navitems.js b/src/config/header.navitems.js index 6736449b83..11de54adc7 100644 --- a/src/config/header.navitems.js +++ b/src/config/header.navitems.js @@ -19,6 +19,10 @@ export default function headerItems(baseUrl = '/', currentLocale = 'en') { label: 'header.docs.ai_unlimited', href: `${baseUrl ?? ''}${locale ?? ''}/ai-unlimited/`, }, + { + label: 'Agent Cookbook', + href: `${baseUrl ?? ''}${locale ?? ''}/agent-cookbook/`, + }, { label: 'header.docs.all_documentation', href: 'https://docs.teradata.com/', diff --git a/src/pages/agent-cookbook.js b/src/pages/agent-cookbook.js new file mode 100644 index 0000000000..c5c2504574 --- /dev/null +++ b/src/pages/agent-cookbook.js @@ -0,0 +1,63 @@ +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import Head from '@docusaurus/Head'; +import Layout from '@theme/Layout'; +import AgentCookbookEditions from '@site/src/components/AgentCookbookFeatures/AgentCookbookEditions'; +import HeroImageUrl from '@site/static/img/hero.webp'; +import Translate, { translate } from '@docusaurus/Translate'; +import Heading from '@theme/Heading'; +import styles from './index.module.css'; + +function HomepageHeader() { + return ( +
+
+
+ + Agent Cookbook + +

+ Recipes, patterns, and best practices for building intelligent agents +

+
+ + Explore Recipes + +
+
+
+ Agent Cookbook +
+
+
+
+ ); +} + +export default function Home() { + return ( + + + Agent Cookbook - Build Intelligent Agents + + + +
+ +
+ + ); +}