fix(src): define MAX_ITERATIONS, disable DEBUG flag;

Add API.md

Author: Gioee

API.md

@@ -0,0 +1,170 @@
+# SQLite Agent API Reference
+
+## Dependencies
+
+**Required:**
+- [sqlite-mcp](../sqlite-mcp) – MCP client for tool access
+- [sqlite-ai](../sqlite-ai) – LLM inference and embeddings
+
+**Optional:**
+- [sqlite-vector](../sqlite-vector) – For vector search (auto-enabled in table mode)
+
+---
+
+## Functions
+
+### `agent_version()`
+
+Returns the extension version.
+
+**Syntax:**
+```sql
+SELECT agent_version();
+```
+
+**Returns:** `TEXT` – Version string (e.g., "0.1.0")
+
+**Example:**
+```sql
+SELECT agent_version();
+-- 0.1.0
+```
+
+---
+
+### `agent_run()`
+
+Runs an autonomous AI agent that uses MCP tools to accomplish a goal.
+
+**Syntax:**
+```sql
+-- MODE 1: Text response
+SELECT agent_run(goal);
+SELECT agent_run(goal, max_iterations);
+
+-- MODE 2: Table extraction
+SELECT agent_run(goal, table_name);
+SELECT agent_run(goal, table_name, max_iterations);
+SELECT agent_run(goal, table_name, max_iterations, system_prompt);
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `goal` | TEXT | Yes | - | Task or goal for the agent |
+| `table_name` | TEXT | No | NULL | Target table (NULL for text mode) |
+| `max_iterations` | INTEGER | No | 5 | Maximum iterations |
+| `system_prompt` | TEXT | No | NULL | Custom system prompt |
+
+**Returns:**
+- **MODE 1 (text):** TEXT – Agent's final response
+- **MODE 2 (table):** TEXT – Status message (e.g., "Inserted 5 rows into listings")
+
+**MODE 1: Text Response**
+
+Agent returns text after using tools.
+
+```sql
+SELECT agent_run('Find affordable apartments in Rome', 8);
+```
+
+Returns:
+```
+I found several affordable apartments in Rome:
+1. Bright Studio - €85/night
+2. Cozy Room - €72/night
+3. Modern Apartment - €95/night
+```
+
+**MODE 2: Table Extraction**
+
+Agent fetches data and populates a table.
+
+```sql
+CREATE TABLE listings (
+  id INTEGER PRIMARY KEY,
+  title TEXT,
+  price REAL,
+  embedding BLOB
+);
+
+SELECT agent_run('Find apartments in Rome under 100 EUR', 'listings', 8);
+-- Returns: "Inserted 5 rows into listings"
+```
+
+**Auto-Features (MODE 2):**
+
+1. **Schema Inspection** – Reads table schema to understand target data structure
+2. **Structured Extraction** – Extracts data matching column names and types
+3. **Transaction Safety** – Wraps all insertions in BEGIN/COMMIT
+4. **Auto-Embeddings** – Generates embeddings for BLOB columns named `*_embedding`
+5. **Auto-Vector Index** – Initializes vector indices when embeddings are created
+
+**Custom System Prompt:**
+
+```sql
+SELECT agent_run(
+  'Find vegan restaurants',
+  'restaurants',
+  10,
+  'You are a restaurant finder. Focus on highly-rated establishments.'
+);
+```
+
+---
+
+## Error Handling
+
+**Common Errors:**
+
+```sql
+-- Not connected to MCP
+SELECT agent_run('Find apartments', 5);
+-- Error: Not connected. Call mcp_connect() first
+
+-- Table doesn't exist
+SELECT agent_run('Find apartments', 'nonexistent', 5);
+-- Error: Table does not exist or has no columns
+
+-- LLM not loaded (table mode)
+SELECT agent_run('Find apartments', 'listings', 5);
+-- Error: Failed to create LLM chat context
+```
+
+**Checking for Errors:**
+
+```sql
+SELECT
+  CASE
+    WHEN result LIKE '%error%' OR result LIKE '%ERROR%'
+    THEN 'Error occurred'
+    ELSE 'Success'
+  END
+FROM (SELECT agent_run('Find apartments', 5) as result);
+```
+
+---
+
+## Performance
+
+**Timing:**
+- **Agent Iterations**: 100ms-10s per iteration (LLM inference)
+- **Tool Calls**: 10-1000ms (network latency)
+- **Embedding Generation**: 10-100ms per text (model-dependent)
+- **Vector Index**: <100ms (initialization)
+
+**Tips:**
+- Use appropriate `max_iterations` (default: 5)
+- Reuse MCP connections (global client persists)
+- Use the Agent in a separated thread
+
+---
+
+## See Also
+
+- [USAGE.md](USAGE.md) – Usage guide and examples
+- [README.md](README.md) – Project overview
+- [sqlite-mcp API](https://github.com/sqliteai/sqlite-mcp/blob/main/API.md) – MCP extension API
+- [sqlite-ai API](https://github.com/sqliteai/sqlite-ai/blob/main/API.md) – AI extension API
+- [sqlite-vector API](https://github.com/sqliteai/sqlite-vector/blob/main/API.md) – Vector extension API

src/sqlite-agent.c

@@ -5,8 +5,9 @@
 //  Created by Gioele Cantoni on 05/11/25.
 //
 
-#define AGENT_DEBUG 1
+#define DEFAULT_AGENT_MAX_ITERATIONS 5
 
+//#define AGENT_DEBUG 1
 #ifdef AGENT_DEBUG
   #define D(x) fprintf(stderr, "[DEBUG] " x "\n")
   #define DF(fmt, ...) fprintf(stderr, "[DEBUG] " fmt "\n", __VA_ARGS__)
@@ -141,7 +142,7 @@ static void agent_run_func(
 
   const char *goal = (const char*)sqlite3_value_text(argv[0]);
   const char *table_name = NULL;
-  int max_iterations = 5;
+  int max_iterations = DEFAULT_AGENT_MAX_ITERATIONS;
   const char *custom_system_prompt = NULL;
 
   if (argc >= 2) {