feat: add recipe caching and extraction functionality

- Introduced a new recipe module for parameterized API-call and SQL pipeline caching.
- Implemented recipe extraction from successful executions using LLM.
- Added context variable utilities for safe access.
- Updated configuration to enable recipe caching with default settings.
- Enhanced README and CLAUDE documentation to reflect new features.
- Included tests for recipe tool creation and integration.

Author: akshay5995

CLAUDE.md

@@ -11,7 +11,8 @@ uv sync --group dev
 
 **Run server:**
 ```bash
-uv run api-agent
+uv run api-agent                    # Local dev
+# Or direct (no clone): uvx --from git+https://github.com/agoda-com/api-agent api-agent
 # Server starts on http://localhost:3000/mcp
 ```
 
@@ -71,6 +72,13 @@ docker run -p 3000:3000 -e OPENAI_API_KEY="..." api-agent
   - **model.py**: LLM config (OpenAI-compatible)
   - **progress.py**: Turn tracking
   - **schema_search.py**: Grep-like schema search tool
+  - **contextvar_utils.py**: Safe ContextVar access helpers
+
+- **api_agent/recipe/**: Parameterized pipeline caching
+  - **store.py**: `RecipeStore` (LRU in-memory cache, thread-safe)
+  - **extractor.py**: Extract reusable recipes from agent runs
+  - **tools.py**: Create dynamic MCP tools from recipes
+  - **common.py**: Recipe validation, execution, parameter binding
 
 - **api_agent/graphql/**: GraphQL client (httpx)
 - **api_agent/rest/**: REST client (httpx) + OpenAPI loader
@@ -104,6 +112,26 @@ Set `X-Poll-Paths` header to enable `poll_until_done` tool:
 - Checks `done_field` (dot-path like `"status"`, `"trips.0.isCompleted"`) against `done_value`
 - Max 20 polls (configurable), default 3s delay
 
+### Recipes
+
+Caches parameterized API call + SQL pipelines from successful agent runs:
+
+```
+Query → Agent executes → Extractor LLM → Recipe stored → Future match → Direct execute
+```
+
+- **Storage**: LRU in-memory (default 64 entries, `RECIPE_CACHE_SIZE`)
+- **Key**: `(api_id, schema_hash)` - auto-invalidates on schema change
+- **Matching**: Fuzzy question similarity via RapidFuzz token matching
+- **Templating**:
+  - GraphQL: `{{param}}` in `query_template`
+  - REST: `{"$param": "name"}` in `path_params`, `query_params`, `body`
+  - SQL: `{{param}}` in SQL strings
+- **Validation**: Recipe must render back to original execution (roundtrip check)
+- **Config**: `ENABLE_RECIPES` (default: True), `RECIPE_CACHE_SIZE` (default: 64)
+
+Key files: `store.py` (LRU cache), `extractor.py` (LLM extraction), `common.py` (execution)
+
 ## Testing Notes
 
 Tests use pytest-asyncio. Mock httpx for HTTP calls. See `tests/test_*.py` for patterns.

README.md

@@ -12,18 +12,22 @@ Point at any GraphQL or REST API. Ask questions in natural language. The agent f
 
 **🔒 Safe by default.** Read-only. Mutations blocked unless explicitly allowed.
 
+**🧠 Recipe learning.** Agent learns from successful queries. Ask once, reuse cached pipelines execute instantly without LLM reasoning.
+
 ## Quick Start
 
-**1. Run:**
-```bash
-git clone https://github.com/agoda-com/api-agent.git
-cd api-agent
-uv sync
-OPENAI_API_KEY=your_key uv run python -m api_agent
-```
+**1. Run (choose one):**
 
-Or with Docker:
 ```bash
+# Direct run (no clone needed)
+OPENAI_API_KEY=your_key uvx --from git+https://github.com/agoda-com/api-agent api-agent
+
+# Or clone & run
+git clone https://github.com/agoda-com/api-agent.git && cd api-agent
+uv sync && OPENAI_API_KEY=your_key uv run api-agent
+
+# Or Docker
+git clone https://github.com/agoda-com/api-agent
 docker build -t api-agent .
 docker run -p 3000:3000 -e OPENAI_API_KEY=your_key api-agent
 ```
@@ -119,6 +123,8 @@ Tool names auto-generated from URL (e.g., `example_query`). Override with `X-API
 | `OPENAI_BASE_URL`             | No       | https://api.openai.com/v1 | Custom LLM endpoint                |
 | `API_AGENT_MODEL_NAME`        | No       | gpt-5.2                   | Model (e.g., gpt-5.2)              |
 | `API_AGENT_PORT`              | No       | 3000                      | Server port                        |
+| `API_AGENT_ENABLE_RECIPES`    | No       | true                      | Enable recipe learning & caching   |
+| `API_AGENT_RECIPE_CACHE_SIZE` | No       | 64                        | Max cached recipes (LRU eviction)  |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | No       | -                         | OpenTelemetry tracing endpoint     |
 
 ---
@@ -181,6 +187,47 @@ flowchart TB
 
 ---
 
+## Recipe Learning
+
+Agent automatically learns reusable patterns from successful queries. When you ask a question, the agent:
+
+1. **Executes** - Runs API calls + SQL post-processing via LLM reasoning
+2. **Extracts** - LLM converts execution trace into parameterized template
+3. **Caches** - Stores recipe keyed by (API, schema hash) with fuzzy question matching
+4. **Reuses** - Similar future questions execute cached recipe instantly (no LLM reasoning)
+
+```mermaid
+flowchart LR
+    subgraph First["First Query"]
+        Q1["'Top 5 users by age'"]
+        A1["Agent reasons"]
+        E1["API + SQL"]
+        R1["Recipe extracted"]
+    end
+
+    subgraph Cache["Recipe Cache"]
+        T["Template:<br/>LIMIT {{limit}}"]
+    end
+
+    subgraph Reuse["Similar Query"]
+        Q2["'Top 10 users by age'"]
+        M["Fuzzy match"]
+        X["Execute directly"]
+    end
+
+    Q1 --> A1 --> E1 --> R1 --> T
+    Q2 --> M --> T --> X
+```
+
+**Recipe structure:**
+- **GraphQL**: `query_template` with `{{param}}` placeholders
+- **REST**: `path_params`, `query_params`, `body` with `{"$param": "name"}` refs
+- **SQL**: `{{param}}` in SQL strings
+
+Recipes auto-expire when schema changes (hash mismatch). Disable with `API_AGENT_ENABLE_RECIPES=false`.
+
+---
+
 ## Development
 
 ```bash

api_agent/agent/contextvar_utils.py

@@ -0,0 +1,28 @@
+"""Utilities for safe ContextVar access."""
+
+from contextvars import ContextVar
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def safe_get_contextvar(var: ContextVar[T], default: T) -> T:
+    """Safe ContextVar access with default.
+
+    Returns value if set, otherwise returns default without setting.
+    """
+    try:
+        return var.get()
+    except LookupError:
+        return default
+
+
+def safe_append_contextvar_list(var: ContextVar[list[T]], item: T) -> None:
+    """Append to ContextVar list if initialized.
+
+    Silently ignores if ContextVar not set (expected in some contexts).
+    """
+    try:
+        var.get().append(item)
+    except LookupError:
+        pass  # Expected - list not initialized for this context