Add LLM inference API endpoints for farmer chat assistant

- Expose stateless LLM inference via /api/v1/llm/ endpoints
- Chat endpoint with optional farm context grounding
- Context validation endpoint to fail fast on invalid metadata
- Batch chat endpoint for bulk analysis (max 10 requests)
- Health check endpoint for monitoring backend status
- Comprehensive test suite and API documentation

Endpoints:
- GET /api/v1/llm/health - Check LLM backend status
- POST /api/v1/llm/chat - Single message inference
- POST /api/v1/llm/validate-context - Validate farm context
- POST /api/v1/llm/chat/batch - Bulk requests (max 10)

Design: Stateless API layer. Conversation history and session
management are handled by external service (web UI, mobile app).

Co-Authored-By: Oz <oz-agent@warp.dev>

LLM_API_DOCS.md

@@ -0,0 +1 @@
+# Farm GPT LLM Inference API\n\nREST API for the farmer chat assistant. Stateless endpoints for LLM inference powered by HuggingFace.\n\n## Overview\n\nThe LLM API is exposed at `/api/v1/llm/` and provides stateless inference endpoints. Your external service (web UI, mobile app, etc.) is responsible for maintaining conversation state and user sessions.\n\n**Key features:**\n- Stateless chat inference\n- Farm context grounding (optional)\n- Context validation before inference\n- Batch requests for bulk analysis\n- Health monitoring\n\n---\n\n## Endpoints\n\n### 1. Health Check\n\n```http\nGET /api/v1/llm/health\n```\n\nVerify LLM backend accessibility and get latency info.\n\n**Response (200 OK):**\n```json\n{\n  \"status\": \"ok\",\n  \"model\": \"mistralai/Mistral-7B-Instruct-v0.1\",\n  \"latency_ms\": 12.5,\n  \"message\": \"LLM backend is reachable\"\n}\n```\n\n**Response (503 Service Unavailable):**\n```json\n{\n  \"status\": \"unavailable\",\n  \"message\": \"LLM backend unavailable: HF token not found...\"\n}\n```\n\n**Use case:** Check backend health before sending requests to `/chat`.\n\n---\n\n### 2. Chat Inference\n\n```http\nPOST /api/v1/llm/chat\n```\n\nSend a message to the farmer assistant and get a response.\n\n**Request:**\n```json\n{\n  \"content\": \"How much water should tomatoes get weekly?\",\n  \"conversation_history\": [\n    {\"role\": \"user\", \"content\": \"What crops grow here?\"},\n    {\"role\": \"assistant\", \"content\": \"Tomatoes, peppers, lettuce...\"}\n  ],\n  \"farm_context\": {\n    \"farm_name\": \"Johnson Farm\",\n    \"crop\": \"tomato\",\n    \"area_ha\": 2.5,\n    \"design_summary\": {}\n  },\n  \"max_tokens\": 256,\n  \"temperature\": 0.7\n}\n```\n\n**Request fields:**\n\n| Field | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `content` | string | ✓ | — | User message (1–2000 chars) |\n| `conversation_history` | array | — | null | Prior messages in `{\"role\": \"user\"|\"assistant\", \"content\": \"...\"}` format |\n| `farm_context` | object | — | null | Farm metadata (see below) |\n| `max_tokens` | integer | — | 256 | Max response length (10–1024) |\n| `temperature` | float | — | 0.7 | Creativity (0=deterministic, 2=very creative) |\n\n**Farm context fields (all optional):**\n- `farm_name`: string — Name of the farm\n- `crop`: string — Crop type (tomato, pepper, lettuce, cucumber, orchard, generic)\n- `area_ha`: number — Farm area in hectares\n- `design_summary`: object — Design metadata from `/rest/v1/design`\n\n**Response (200 OK):**\n```json\n{\n  \"content\": \"For tomatoes, apply 25-40mm of water per week...\",\n  \"timestamp\": \"2026-06-18T12:30:00+00:00\",\n  \"model\": \"mistralai/Mistral-7B-Instruct-v0.1\",\n  \"tokens_used\": 145,\n  \"latency_ms\": 2450,\n  \"metadata\": {\n    \"farm_context_provided\": true,\n    \"conversation_history_length\": 2\n  }\n}\n```\n\n**Response (422 Validation Error):**\n```json\n{\n  \"detail\": {\n    \"code\": \"invalid_farm_context\",\n    \"message\": \"Farm context validation failed\",\n    \"errors\": [\"'area_ha' must be a number\"]\n  }\n}\n```\n\n**Response (500 Inference Error):**\n```json\n{\n  \"detail\": \"LLM inference failed: Request timed out after 30s\"\n}\n```\n\n**Use case:** Core endpoint for multi-turn conversations. Client maintains history and passes it with each request.\n\n---\n\n### 3. Validate Context\n\n```http\nPOST /api/v1/llm/validate-context\n```\n\nValidate farm context before using it in chat. Catch issues early without spending LLM tokens.\n\n**Request:**\n```json\n{\n  \"farm_context\": {\n    \"farm_name\": \"Smith Farm\",\n    \"crop\": \"lettuce\",\n    \"area_ha\": 0.5\n  }\n}\n```\n\n**Response (200 OK):**\n```json\n{\n  \"valid\": true,\n  \"warnings\": [],\n  \"errors\": []\n}\n```\n\n**Response with warnings:**\n```json\n{\n  \"valid\": true,\n  \"warnings\": [\n    \"Unknown crop 'sugarcanr'. Expected one of: tomato, pepper, lettuce, cucumber, orchard, generic\"\n  ],\n  \"errors\": []\n}\n```\n\n**Response with errors:**\n```json\n{\n  \"valid\": false,\n  \"warnings\": [],\n  \"errors\": [\"'area_ha' must be a number\"]\n}\n```\n\n**Validation rules:**\n- Required (fail): `area_ha` is a number if present\n- Recommended: `farm_name`, `crop`, `area_ha`\n- Optional warnings: Unknown crop, missing recommended fields\n\n**Use case:** Pre-validate context before `/chat` to avoid wasting LLM tokens on invalid requests.\n\n---\n\n### 4. Batch Chat\n\n```http\nPOST /api/v1/llm/chat/batch\n```\n\nSend multiple messages in a single request (up to 10).\n\n**Request:**\n```json\n[\n  {\n    \"content\": \"What is drip irrigation?\",\n    \"max_tokens\": 100\n  },\n  {\n    \"content\": \"How do I install valves?\",\n    \"max_tokens\": 100\n  },\n  {\n    \"content\": \"What is emitter spacing?\",\n    \"max_tokens\": 100,\n    \"farm_context\": {\n      \"crop\": \"tomato\",\n      \"area_ha\": 1.0\n    }\n  }\n]\n```\n\n**Response (200 OK):**\n```json\n[\n  {\n    \"content\": \"Drip irrigation is a method of watering plants...\",\n    \"timestamp\": \"2026-06-18T12:30:00+00:00\",\n    \"model\": \"mistralai/Mistral-7B-Instruct-v0.1\",\n    \"tokens_used\": 120,\n    \"latency_ms\": 2100,\n    \"metadata\": {\"farm_context_provided\": false}\n  },\n  {\n    \"content\": \"To install valves: 1) Plan your zones...\",\n    \"timestamp\": \"2026-06-18T12:30:02+00:00\",\n    \"model\": \"mistralai/Mistral-7B-Instruct-v0.1\",\n    \"tokens_used\": 135,\n    \"latency_ms\": 1950,\n    \"metadata\": {\"farm_context_provided\": false}\n  },\n  {\n    \"content\": \"Emitter spacing depends on soil type...\",\n    \"timestamp\": \"2026-06-18T12:30:04+00:00\",\n    \"model\": \"mistralai/Mistral-7B-Instruct-v0.1\",\n    \"tokens_used\": 110,\n    \"latency_ms\": 2050,\n    \"metadata\": {\"farm_context_provided\": true}\n  }\n]\n```\n\n**Constraints:**\n- Max 10 requests per batch\n- Each request is independent (no conversation history carried between items)\n- Returns response array in same order as request\n\n**Use case:** Bulk analysis, FAQ generation, or multi-question surveys.\n\n---\n\n## Error Handling\n\n### HTTP Status Codes\n\n| Code | Meaning | Example |\n|------|---------|----------|\n| 200 | Success | Chat response generated |\n| 422 | Validation Error | Invalid farm context or oversized content |\n| 500 | Inference Error | LLM backend failure or timeout |\n| 503 | Service Unavailable | HF token not configured |\n\n### Common Error Scenarios\n\n**Missing HF token:**\n```bash\ncurl http://localhost:7860/api/v1/llm/health\n# → 503 Service Unavailable\n```\n\n**Oversized content (>2000 chars):**\n```bash\ncurl -X POST http://localhost:7860/api/v1/llm/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"'\"'\"'x{3000}'\"'\"'\"}'\n# → 422 Validation Error\n```\n\n**Invalid farm context:**\n```bash\ncurl -X POST http://localhost:7860/api/v1/llm/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"...\", \"farm_context\": {\"area_ha\": \"not a number\"}}'\n# → 422 Validation Error with error details\n```\n\n---\n\n## Integration Examples\n\n### JavaScript/Web UI\n\n```javascript\n// Simple chat\nconst response = await fetch('http://localhost:7860/api/v1/llm/chat', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    content: 'How often should I water?',\n    farm_context: {\n      farm_name: 'My Farm',\n      crop: 'tomato',\n      area_ha: 1.5\n    },\n    max_tokens: 200,\n    temperature: 0.7\n  })\n});\n\nconst { content, latency_ms } = await response.json();\nconsole.log(`Response (${latency_ms}ms): ${content}`);\n\n// Multi-turn conversation\nconst messages = [];\n\nfunction addMessage(role, content) {\n  messages.push({ role, content });\n}\n\nasync function chat(userMessage) {\n  addMessage('user', userMessage);\n  const response = await fetch('http://localhost:7860/api/v1/llm/chat', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({\n      content: userMessage,\n      conversation_history: messages.slice(0, -1),  // Exclude current user message\n      farm_context: { crop: 'tomato', area_ha: 2.0 }\n    })\n  });\n  const { content } = await response.json();\n  addMessage('assistant', content);\n  return content;\n}\n\nawait chat('What is drip irrigation?');\nawait chat('Can I use it for peppers?');\n```\n\n### Python Client\n\n```python\nimport requests\n\nclass FarmerChatClient:\n    def __init__(self, base_url='http://localhost:7860'):\n        self.base_url = base_url\n        self.history = []\n        self.farm_context = {}\n    \n    def set_farm_context(self, **kwargs):\n        \"\"\"Set farm metadata (crop, area_ha, farm_name, etc.)\"\"\"\n        self.farm_context.update(kwargs)\n    \n    def chat(self, message: str, max_tokens: int = 256) -> str:\n        \"\"\"Send a message and get a response.\"\"\"\n        response = requests.post(\n            f'{self.base_url}/api/v1/llm/chat',\n            json={\n                'content': message,\n                'conversation_history': self.history,\n                'farm_context': self.farm_context,\n                'max_tokens': max_tokens,\n                'temperature': 0.7,\n            }\n        )\n        response.raise_for_status()\n        \n        data = response.json()\n        assistant_message = data['content']\n        \n        # Add to conversation history\n        self.history.append({'role': 'user', 'content': message})\n        self.history.append({'role': 'assistant', 'content': assistant_message})\n        \n        return assistant_message\n\n# Usage\nclient = FarmerChatClient()\nclient.set_farm_context(farm_name='Johnson Farm', crop='tomato', area_ha=2.5)\n\nprint(client.chat('How often should I water tomatoes?'))\nprint(client.chat('What about in dry seasons?'))  # Uses conversation history\n```\n\n### cURL Examples\n\n```bash\n# Health check\ncurl http://localhost:7860/api/v1/llm/health | jq\n\n# Simple chat\ncurl -X POST http://localhost:7860/api/v1/llm/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"What is drip irrigation?\",\n    \"max_tokens\": 150\n  }' | jq '.content'\n\n# Chat with farm context\ncurl -X POST http://localhost:7860/api/v1/llm/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"How much water should I apply?\",\n    \"farm_context\": {\n      \"farm_name\": \"Smith Farm\",\n      \"crop\": \"tomato\",\n      \"area_ha\": 1.5\n    },\n    \"max_tokens\": 200\n  }' | jq '.content'\n\n# Validate context before chat\ncurl -X POST http://localhost:7860/api/v1/llm/validate-context \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"farm_context\": {\n      \"crop\": \"invalid_crop\",\n      \"area_ha\": 0.5\n    }\n  }' | jq\n\n# Batch requests\ncurl -X POST http://localhost:7860/api/v1/llm/chat/batch \\\n  -H \"Content-Type: application/json\" \\\n  -d '[\n    {\"content\": \"What is drip irrigation?\", \"max_tokens\": 100},\n    {\"content\": \"How do I install valves?\", \"max_tokens\": 100}\n  ]' | jq\n```\n\n---\n\n## Performance Considerations\n\n### Latency\n- Typical: 1.5–3 seconds for 100–200 token responses\n- First request: May take 5–10s if model is loading\n- Use `max_tokens` to control response length and latency\n\n### Throughput\n- HuggingFace Inference API has request rate limits\n- Use batch endpoint for multiple questions (more efficient)\n- Implement client-side request queuing if needed\n\n### Token Estimation\n- Roughly 1 token ≈ 4 characters\n- Response `tokens_used` includes both input and output\n\n---\n\n## Configuration\n\n### Environment Setup\n\nThe API requires a HuggingFace API token:\n\n```bash\n# Option 1: Environment variable\nexport HF_TOKEN=hf_your_token_here\npython app.py\n\n# Option 2: secret.txt file (same directory as app.py)\necho \"hf_your_token_here\" > secret.txt\npython app.py\n\n# Option 3: Passed to FarmerAssistant directly (in code)\n# See llm_chat.py for details\n```\n\n### Model Selection\n\nDefault model: `mistralai/Mistral-7B-Instruct-v0.1`\n\nTo use a different model, edit `llm_chat.py`:\n\n```python\nassistant = FarmerAssistant(\n    model_id=\"HuggingFace/ModelName\",\n    api_token=\"hf_your_token_here\"\n)\n```\n\n---\n\n## Testing\n\nRun the test suite to verify all endpoints:\n\n```bash\n# Terminal 1: Start the server\npython app.py\n\n# Terminal 2: Run tests\npython test_llm_api.py\n```\n\nThis tests:\n- Health check\n- Simple and contextual chat\n- Multi-turn conversations\n- Context validation\n- Batch requests\n- Error handling\n\n---\n\n## OpenAPI Documentation\n\nOnce the server is running, view interactive API docs:\n\n```\nhttp://localhost:7860/docs\n```\n\nThis page (auto-generated by FastAPI) shows all endpoints, request/response schemas, and try-it-out forms.\n"

app.py

@@ -645,10 +645,12 @@ from fastapi import FastAPI, Request  # noqa: E402
 from fastapi.exceptions import RequestValidationError  # noqa: E402
 from fastapi.responses import JSONResponse  # noqa: E402
 from rest_api import build_router, _format_validation_error  # noqa: E402
+from llm_api import build_router as build_llm_router  # noqa: E402
 
 # Create the FastAPI app BEFORE mounting Gradio so exception handlers are registered
 api = FastAPI(title="Farm Layout Model API")
 api.include_router(build_router())
+api.include_router(build_llm_router())
 
 # Add custom validation error handler for user-friendly messages
 # This must be done BEFORE mounting Gradio

llm_api.py

@@ -0,0 +1,384 @@
+"""
+REST API layer for LLM inference — farmer chat assistant.
+
+Exposes HuggingFace Inference API through standardized endpoints.
+Conversation state management is handled by the client/external service.
+
+Why this exists:
+    The FarmerAssistant class only wraps HTTP calls to HuggingFace.
+    This module translates that into REST endpoints so external clients
+    (web UIs, mobile apps, third-party services) can interact with the LLM
+    without importing Python modules.
+
+The endpoints here are stateless — conversation history, user sessions,
+and context persistence are the caller's responsibility.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from llm_chat import FarmerAssistant
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Request/Response Models
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+class ChatRequest(BaseModel):
+    """Single LLM inference request.
+    
+    The caller provides the user's message. Conversation history and context
+    are optional — the client maintains state.
+    """
+    content: str = Field(
+        ...,
+        min_length=1,
+        max_length=2000,
+        description="User's question or statement for the farmer assistant"
+    )
+    
+    conversation_history: Optional[List[Dict[str, str]]] = Field(
+        default=None,
+        description=(
+            "Previous messages in [{'role': 'user', 'content': '...'}, "
+            "{'role': 'assistant', 'content': '...'}] format. "
+            "Used to ground the response in prior context."
+        )
+    )
+    
+    farm_context: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Optional farm metadata to include in the system context. "
+            "Example: {'farm_name': 'Johnson Farm', 'crop': 'tomato', 'area_ha': 2.5}"
+        )
+    )
+    
+    max_tokens: int = Field(
+        default=256,
+        ge=10,
+        le=1024,
+        description="Maximum tokens in the response"
+    )
+    
+    temperature: float = Field(
+        default=0.7,
+        ge=0.0,
+        le=2.0,
+        description="Creativity level (0=deterministic, 1=creative, 2=very creative)"
+    )
+
+
+class ChatResponse(BaseModel):
+    """LLM inference response."""
+    content: str = Field(..., description="Assistant's response")
+    timestamp: str = Field(..., description="ISO8601 timestamp when response was generated")
+    model: str = Field(..., description="Model ID used (e.g., 'mistral-7b-instruct')")
+    tokens_used: Optional[int] = Field(
+        default=None,
+        description="Approximate tokens consumed by request (input + output)"
+    )
+    latency_ms: float = Field(..., description="Response time in milliseconds")
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Additional metadata (e.g., warning flags, model-specific info)"
+    )
+
+
+class HealthResponse(BaseModel):
+    """LLM backend health status."""
+    status: str = Field(..., description="'ok' or 'unavailable'")
+    model: str = Field(..., description="Active model ID")
+    latency_ms: Optional[float] = Field(
+        default=None,
+        description="Milliseconds to reach the LLM backend"
+    )
+    message: Optional[str] = Field(
+        default=None,
+        description="Human-readable status message"
+    )
+
+
+class ContextValidationRequest(BaseModel):
+    """Validate farm context before using in chat."""
+    farm_context: Dict[str, Any] = Field(
+        ...,
+        description="Farm metadata to validate (e.g., design_summary, crop, area)"
+    )
+
+
+class ContextValidationResponse(BaseModel):
+    """Result of context validation."""
+    valid: bool = Field(..., description="Whether the context is valid")
+    warnings: List[str] = Field(
+        default_factory=list,
+        description="Non-fatal issues (e.g., missing recommended fields)"
+    )
+    errors: List[str] = Field(
+        default_factory=list,
+        description="Fatal issues that should be resolved before use"
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Helper: Lazy-load FarmerAssistant singleton
+# ──────────────────────────────────────────────────────────────────────────────
+
+_ASSISTANT = None
+
+
+def get_assistant() -> FarmerAssistant:
+    """Lazy-load the FarmerAssistant on first use.
+    
+    Raises HTTPException(503) if the token is not configured.
+    """
+    global _ASSISTANT
+    if _ASSISTANT is None:
+        try:
+            _ASSISTANT = FarmerAssistant()
+        except ValueError as e:
+            raise HTTPException(
+                status_code=503,
+                detail=f"LLM backend unavailable: {str(e)}",
+            )
+    return _ASSISTANT
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Context Validation
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _validate_farm_context(context: Dict[str, Any]) -> tuple[bool, List[str], List[str]]:
+    """
+    Validate farm context for use in chat.
+    
+    Returns: (is_valid, warnings, errors)
+    """
+    warnings = []
+    errors = []
+    
+    # Optional but recommended fields
+    recommended = ["farm_name", "crop", "area_ha"]
+    present = set(context.keys())
+    missing_recommended = [f for f in recommended if f not in present]
+    if missing_recommended:
+        warnings.append(f"Missing recommended fields: {', '.join(missing_recommended)}")
+    
+    # Validate field types if present
+    if "area_ha" in context:
+        try:
+            float(context["area_ha"])
+        except (TypeError, ValueError):
+            errors.append("'area_ha' must be a number")
+    
+    if "crop" in context:
+        valid_crops = ["tomato", "pepper", "lettuce", "cucumber", "orchard", "generic"]
+        if str(context["crop"]).lower() not in valid_crops:
+            warnings.append(
+                f"Unknown crop '{context['crop']}'. "
+                f"Expected one of: {', '.join(valid_crops)}"
+            )
+    
+    # design_summary can be complex; just check it exists if referenced
+    if "design_summary" in context and not isinstance(context["design_summary"], dict):
+        warnings.append("'design_summary' should be a dict")
+    
+    is_valid = len(errors) == 0
+    return is_valid, warnings, errors
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Router
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def build_router() -> APIRouter:
+    """Build the LLM inference API router."""
+    router = APIRouter(prefix="/api/v1/llm", tags=["chat"])
+    
+    @router.get("/health")
+    def health() -> HealthResponse:
+        """
+        Check if the LLM backend is accessible.
+        
+        Returns latency to help clients decide whether to retry or fallback.
+        """
+        try:
+            assistant = get_assistant()
+            start = time.perf_counter()
+            # Simple test: check that we can reach the API
+            # (Without actually sending tokens to the model)
+            _ = assistant.api_token is not None
+            elapsed_ms = (time.perf_counter() - start) * 1000
+            
+            return HealthResponse(
+                status="ok",
+                model=assistant.model_id,
+                latency_ms=elapsed_ms,
+                message="LLM backend is reachable",
+            )
+        except HTTPException as e:
+            # Token not configured
+            raise e
+        except Exception as e:
+            raise HTTPException(
+                status_code=503,
+                detail=f"LLM health check failed: {str(e)}",
+            )
+    
+    @router.post("/chat")
+    def chat(req: ChatRequest) -> ChatResponse:
+        """
+        Send a message to the farmer assistant and get a response.
+        
+        The caller is responsible for maintaining conversation history.
+        Pass prior messages in `conversation_history` if you want context.
+        
+        Optional `farm_context` grounds the response in your farm data
+        (e.g., crop, area, design summary).
+        """
+        try:
+            assistant = get_assistant()
+        except HTTPException:
+            raise
+        
+        # Enrich the message with farm context if provided
+        farm_context_str = ""
+        if req.farm_context:
+            # Validate context first
+            is_valid, warnings, errors = _validate_farm_context(req.farm_context)
+            if errors:
+                raise HTTPException(
+                    status_code=422,
+                    detail={
+                        "code": "invalid_farm_context",
+                        "message": "Farm context validation failed",
+                        "errors": errors,
+                    },
+                )
+            
+            # Build a brief context string to prepend to the user message.
+            farm_name = req.farm_context.get("farm_name", "Your farm")
+            crop = req.farm_context.get("crop", "unknown crop")
+            area = req.farm_context.get("area_ha", "unknown area")
+            farm_context_str = f"Farm context: {farm_name}, growing {crop}, {area} ha. "
+        
+        # Send to LLM
+        start = time.perf_counter()
+        try:
+            response_text = assistant.chat(
+                user_message=f"{farm_context_str}{req.content}",
+                conversation_history=req.conversation_history,
+                max_tokens=req.max_tokens,
+                temperature=req.temperature,
+            )
+        except Exception as e:
+            raise HTTPException(
+                status_code=500,
+                detail=f"LLM inference failed: {str(e)}",
+            )
+        
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        
+        # Rough token estimation (1 token ≈ 4 chars)
+        estimated_tokens = (
+            len(req.content) + len(response_text) + len(farm_context_str)
+        ) // 4
+        
+        from datetime import datetime, timezone
+        timestamp = datetime.now(timezone.utc).isoformat()
+        
+        return ChatResponse(
+            content=response_text,
+            timestamp=timestamp,
+            model=assistant.model_id,
+            tokens_used=estimated_tokens,
+            latency_ms=elapsed_ms,
+            metadata={
+                "farm_context_provided": req.farm_context is not None,
+                "conversation_history_length": len(req.conversation_history or []),
+            },
+        )
+    
+    @router.post("/validate-context")
+    def validate_context(req: ContextValidationRequest) -> ContextValidationResponse:
+        """
+        Validate farm context before using it in chat requests.
+        
+        Helps clients catch issues early without spending LLM tokens.
+        """
+        is_valid, warnings, errors = _validate_farm_context(req.farm_context)
+        
+        return ContextValidationResponse(
+            valid=is_valid,
+            warnings=warnings,
+            errors=errors,
+        )
+    
+    @router.post("/chat/batch")
+    def chat_batch(requests: List[ChatRequest]) -> List[ChatResponse]:
+        """
+        Send multiple messages in a batch (useful for bulk analysis).
+        
+        Note: Each request is independent — no conversation history carried
+        between items. For multi-turn conversations, use POST /api/v1/llm/chat
+        with explicit history in each call.
+        
+        Rate-limited: max 10 requests per batch.
+        """
+        if len(requests) > 10:
+            raise HTTPException(
+                status_code=422,
+                detail="Batch size limited to 10 requests",
+            )
+        
+        try:
+            assistant = get_assistant()
+        except HTTPException:
+            raise
+        
+        responses = []
+        for req in requests:
+            try:
+                start = time.perf_counter()
+                response_text = assistant.chat(
+                    user_message=req.content,
+                    conversation_history=req.conversation_history,
+                    max_tokens=req.max_tokens,
+                    temperature=req.temperature,
+                )
+                elapsed_ms = (time.perf_counter() - start) * 1000
+                estimated_tokens = (len(req.content) + len(response_text)) // 4
+                
+                from datetime import datetime, timezone
+                timestamp = datetime.now(timezone.utc).isoformat()
+                
+                responses.append(ChatResponse(
+                    content=response_text,
+                    timestamp=timestamp,
+                    model=assistant.model_id,
+                    tokens_used=estimated_tokens,
+                    latency_ms=elapsed_ms,
+                    metadata={
+                        "farm_context_provided": req.farm_context is not None,
+                    },
+                ))
+            except Exception as e:
+                # Return error in same list position
+                responses.append(ChatResponse(
+                    content=f"Error: {str(e)}",
+                    timestamp="",
+                    model="",
+                    latency_ms=0,
+                    metadata={"error": True},
+                ))
+        
+        return responses
+    
+    return router

test_llm_api.py

@@ -0,0 +1,244 @@
+"""
+Test script for LLM inference API endpoints.
+
+Run the server first:
+    python app.py
+
+Then in another terminal:
+    python test_llm_api.py
+"""
+
+import requests
+import json
+from typing import Dict, Any
+
+
+BASE_URL = "http://localhost:7860"
+
+
+def test_health() -> None:
+    """Test the health endpoint."""
+    print("\n=== Testing GET /api/v1/llm/health ===")
+    response = requests.get(f"{BASE_URL}/api/v1/llm/health")
+    print(f"Status: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    assert response.status_code == 200 or response.status_code == 503
+
+
+def test_chat_simple() -> None:
+    """Test basic chat without context."""
+    print("\n=== Testing POST /api/v1/llm/chat (simple) ===")
+    payload = {
+        "content": "What is drip irrigation?",
+        "max_tokens": 150,
+        "temperature": 0.7,
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/chat", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Model: {data.get('model')}")
+    print(f"Content: {data.get('content')}")
+    print(f"Latency (ms): {data.get('latency_ms')}")
+    assert response.status_code == 200 or response.status_code == 500
+
+
+def test_chat_with_context() -> None:
+    """Test chat with farm context."""
+    print("\n=== Testing POST /api/v1/llm/chat (with farm context) ===")
+    payload = {
+        "content": "How much water should I apply weekly?",
+        "farm_context": {
+            "farm_name": "Johnson Farm",
+            "crop": "tomato",
+            "area_ha": 2.5,
+        },
+        "max_tokens": 200,
+        "temperature": 0.5,
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/chat", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Model: {data.get('model')}")
+    print(f"Content: {data.get('content')}")
+    print(f"Latency (ms): {data.get('latency_ms')}")
+    print(f"Metadata: {json.dumps(data.get('metadata'), indent=2)}")
+    assert response.status_code == 200 or response.status_code == 500
+
+
+def test_chat_with_history() -> None:
+    """Test chat with conversation history."""
+    print("\n=== Testing POST /api/v1/llm/chat (with history) ===")
+    payload = {
+        "content": "What about pepper crops?",
+        "conversation_history": [
+            {"role": "user", "content": "How much water should I apply weekly?"},
+            {"role": "assistant", "content": "For tomatoes, 25-40mm per week is typical."},
+        ],
+        "farm_context": {
+            "farm_name": "Johnson Farm",
+            "crop": "pepper",
+            "area_ha": 1.5,
+        },
+        "max_tokens": 200,
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/chat", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Content: {data.get('content')}")
+    print(f"Conversation history length: {data.get('metadata', {}).get('conversation_history_length')}")
+    assert response.status_code == 200 or response.status_code == 500
+
+
+def test_validate_context_valid() -> None:
+    """Test context validation with valid data."""
+    print("\n=== Testing POST /api/v1/llm/validate-context (valid) ===")
+    payload = {
+        "farm_context": {
+            "farm_name": "Smith Farm",
+            "crop": "lettuce",
+            "area_ha": 0.5,
+        }
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/validate-context", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Valid: {data.get('valid')}")
+    print(f"Warnings: {data.get('warnings')}")
+    print(f"Errors: {data.get('errors')}")
+    assert response.status_code == 200
+    assert data.get('valid') is True
+
+
+def test_validate_context_invalid_crop() -> None:
+    """Test context validation with invalid crop."""
+    print("\n=== Testing POST /api/v1/llm/validate-context (invalid crop) ===")
+    payload = {
+        "farm_context": {
+            "farm_name": "Smith Farm",
+            "crop": "invalid_crop",
+            "area_ha": 0.5,
+        }
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/validate-context", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Valid: {data.get('valid')}")
+    print(f"Warnings: {data.get('warnings')}")
+    assert response.status_code == 200
+    # Should still be valid (warnings don't fail validation)
+    assert data.get('valid') is True
+
+
+def test_validate_context_invalid_area() -> None:
+    """Test context validation with invalid area type."""
+    print("\n=== Testing POST /api/v1/llm/validate-context (invalid area) ===")
+    payload = {
+        "farm_context": {
+            "farm_name": "Smith Farm",
+            "crop": "tomato",
+            "area_ha": "not a number",
+        }
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/validate-context", json=payload)
+    print(f"Status: {response.status_code}")
+    data = response.json()
+    print(f"Valid: {data.get('valid')}")
+    print(f"Errors: {data.get('errors')}")
+    assert response.status_code == 200
+    assert data.get('valid') is False
+
+
+def test_batch_chat() -> None:
+    """Test batch chat endpoint."""
+    print("\n=== Testing POST /api/v1/llm/chat/batch ===")
+    payload = [
+        {
+            "content": "What is drip irrigation?",
+            "max_tokens": 100,
+        },
+        {
+            "content": "How do I install valves?",
+            "max_tokens": 100,
+        },
+        {
+            "content": "What is emitter spacing?",
+            "max_tokens": 100,
+            "farm_context": {
+                "crop": "tomato",
+                "area_ha": 1.0,
+            }
+        },
+    ]
+    response = requests.post(f"{BASE_URL}/api/v1/llm/chat/batch", json=payload)
+    print(f"Status: {response.status_code}")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"Number of responses: {len(data)}")
+        for i, resp in enumerate(data):
+            print(f"\nResponse {i+1}:")
+            print(f"  Content: {resp.get('content')[:100]}...")
+            print(f"  Latency: {resp.get('latency_ms'):.1f}ms")
+
+
+def test_chat_invalid_request() -> None:
+    """Test chat with invalid request (missing required field)."""
+    print("\n=== Testing POST /api/v1/llm/chat (invalid request) ===")
+    payload = {
+        "max_tokens": 100,
+        # Missing required 'content' field
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/chat", json=payload)
+    print(f"Status: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    assert response.status_code == 422
+
+
+def test_chat_oversized_request() -> None:
+    """Test chat with oversized content."""
+    print("\n=== Testing POST /api/v1/llm/chat (oversized content) ===")
+    payload = {
+        "content": "x" * 3000,  # Exceeds max_length of 2000
+    }
+    response = requests.post(f"{BASE_URL}/api/v1/llm/chat", json=payload)
+    print(f"Status: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    assert response.status_code == 422
+
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("LLM Inference API Test Suite")
+    print("=" * 70)
+    
+    try:
+        # Health check first
+        test_health()
+        
+        # Basic tests
+        test_chat_simple()
+        test_chat_with_context()
+        test_chat_with_history()
+        
+        # Context validation tests
+        test_validate_context_valid()
+        test_validate_context_invalid_crop()
+        test_validate_context_invalid_area()
+        
+        # Batch test
+        test_batch_chat()
+        
+        # Error handling tests
+        test_chat_invalid_request()
+        test_chat_oversized_request()
+        
+        print("\n" + "=" * 70)
+        print("✅ All tests completed!")
+        print("=" * 70)
+        
+    except requests.exceptions.ConnectionError:
+        print("\n❌ Error: Could not connect to server.")
+        print("   Make sure the server is running: python app.py")
+    except Exception as e:
+        print(f"\n❌ Unexpected error: {e}")
+        import traceback
+        traceback.print_exc()