Add docs for API & the agent architecture (#22)

* Add docs for API & the agent
* Add reAct arch diagram

docs/agents/index.md

@@ -1,3 +0,0 @@
-# Geo Assistant Agent
-
-The Geo Assistant agent is a LLM-powered agent that can answer questions and perform tasks related to locations and geographic data.

docs/api/index.md

@@ -0,0 +1,106 @@
+# API Reference
+
+The Geo Assistant API provides a streaming chat endpoint for geographic queries.
+
+## Base URL
+
+```
+http://localhost:8000
+```
+
+## Endpoint
+
+### POST /chat
+
+Stream chat responses from the geographic assistant agent.
+
+**Request Body**
+
+```json
+{
+  "thread_id": "uuid-string",
+  "agent_state_input": {
+    "messages": [
+      {
+        "type": "human",
+        "content": "Your question here"
+      }
+    ]
+  }
+}
+```
+
+**Schema**
+
+- `thread_id` (string): UUID for conversation thread
+- `agent_state_input` (object):
+  - `messages` (array): Array of message objects with `type` and `content`
+
+**Response**
+
+Streaming NDJSON format (`application/x-ndjson`). Each line contains:
+
+```json
+{
+  "thread_id": "uuid-string",
+  "state": {
+    "messages": [...],
+    "place": {...},
+    "search_area": {...},
+    "naip_img_bytes": {...}
+  }
+}
+```
+
+**Example**
+
+```bash
+curl -X POST http://localhost:8000/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "thread_id": "123e4567-e89b-12d3-a456-426614174000",
+    "agent_state_input": {
+      "messages": [{"type": "human", "content": "Your question"}]
+    }
+  }'
+```
+
+**Python Example**
+
+```python
+import json
+import uuid
+import httpx
+
+thread_id = str(uuid.uuid4())
+
+request_body = {
+    "thread_id": thread_id,
+    "agent_state_input": {
+        "messages": [{"type": "human", "content": "Your question"}]
+    },
+}
+
+with httpx.stream(
+    "POST",
+    "http://localhost:8000/chat",
+    json=request_body,
+    timeout=360.0,
+) as response:
+    response.raise_for_status()
+    
+    for line in response.iter_lines():
+        if not line:
+            continue
+        
+        data = json.loads(line)
+        state = data.get("state", {})
+        messages = state.get("messages", [])
+        
+        # Process messages
+        for msg in messages:
+            print(f"{msg['type']}: {msg['content']}")
+
+        # Process state updates
+        # ...
+```

docs/index.md

@@ -1,3 +1,29 @@
-# Geo Assistant
+# Geo Assistant 
 
-A geographic assistant that helps answer questions and perform tasks related to locations and geographic data.
+The Geo Assistant agent is a LangGraph-based [ReAct agent](https://arxiv.org/abs/2210.03629) that can answer questions and perform tasks related to locations and geographic data.
+
+## Architecture
+
+<img src="assets/architecture.png" alt="Architecture" width="100%" style="max-width: 400px;">
+
+The agent follows the ReAct (Reasoning + Acting) pattern, which interleaves reasoning traces and task-specific actions to solve queries. It uses LangGraph to manage state transitions and tool execution.
+
+## Available Tools
+
+The agent has access to the following [tools](tools/index.md):
+
+- **get_place**: Retrieve place information from the Overture Maps database
+- **get_search_area**: Create a buffer area (in km) around a place defined in the agent state
+- **fetch_naip_img**: Fetch NAIP aerial imagery for a given area and date range
+- **summarize_sat_img**: Analyze and summarize satellite image contents using an LLM
+
+## State Management
+
+The agent maintains the following state throughout the conversation:
+
+- **messages**: The conversation history (always updated with each interaction)
+- **place**: Current place feature from Overture Maps (updated by `get_place` tool)
+- **search_area**: Buffer area around the place (updated by `get_search_area` tool)
+- **naip_img_bytes**: NAIP imagery data (updated by `fetch_naip_img` tool)
+
+Tools update the state based on user queries, and these state changes are reflected in the `Streamlit` frontend in real-time.

mkdocs.yml

@@ -23,7 +23,7 @@ extra:
 nav:
   - Home: index.md
   - Tools: tools/index.md
-  - Agents: agents/index.md
+  - API: api/index.md
 
 watch:
   - docs