API_QUICK_REFERENCE.md

# Farm GPT LLM API — Quick Reference\n\n## 🌐 Public API URL\n\n```\nhttps://uniphy-farm-layout-model.hf.space\n```\n\n## 📚 Interactive API Docs\n\n```\nhttps://uniphy-farm-layout-model.hf.space/docs\n```\n\n---\n\n## 🚀 Endpoints at a Glance\n\n### GET `/api/v1/llm/health`\nCheck LLM backend status and latency.\n\n```bash\ncurl https://uniphy-farm-layout-model.hf.space/api/v1/llm/health\n```\n\n---\n\n### POST `/api/v1/llm/chat`\nCore inference endpoint. Stateless — you manage conversation history.\n\n```bash\ncurl -X POST https://uniphy-farm-layout-model.hf.space/api/v1/llm/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"content\": \"How much water for tomatoes?\",\n    \"farm_context\": {\n      \"farm_name\": \"Johnson Farm\",\n      \"crop\": \"tomato\",\n      \"area_ha\": 2.5\n    },\n    \"max_tokens\": 200,\n    \"temperature\": 0.7\n  }'\n```\n\n**Request fields:**\n- `content` (required): User message (max 2000 chars)\n- `conversation_history` (optional): Prior messages for context\n- `farm_context` (optional): Farm metadata (farm_name, crop, area_ha, design_summary)\n- `max_tokens` (default 256): Response length (10–1024)\n- `temperature` (default 0.7): Creativity (0–2)\n\n**Response:** Chat response with timestamp, model, tokens, latency\n\n---\n\n### POST `/api/v1/llm/validate-context`\nValidate farm context before sending to chat (fail fast).\n\n```bash\ncurl -X POST https://uniphy-farm-layout-model.hf.space/api/v1/llm/validate-context \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"farm_context\": {\n      \"crop\": \"tomato\",\n      \"area_ha\": 1.5\n    }\n  }'\n```\n\n**Response:** `{\"valid\": true, \"warnings\": [], \"errors\": []}`\n\n---\n\n### POST `/api/v1/llm/chat/batch`\nBulk requests (max 10). Each request independent.\n\n```bash\ncurl -X POST https://uniphy-farm-layout-model.hf.space/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  ]'\n```\n\n**Response:** Array of responses in same order as requests\n\n---\n\n## 💻 Language Examples\n\n### JavaScript\n```javascript\nconst response = await fetch('https://uniphy-farm-layout-model.hf.space/api/v1/llm/chat', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    content: 'How much water should I apply?',\n    farm_context: { crop: 'tomato', area_ha: 2.0 },\n    max_tokens: 200\n  })\n});\nconst { content, latency_ms } = await response.json();\nconsole.log(`${content} (${latency_ms}ms)`);\n```\n\n### Python\n```python\nimport requests\n\nresponse = requests.post(\n    'https://uniphy-farm-layout-model.hf.space/api/v1/llm/chat',\n    json={\n        'content': 'How much water should I apply?',\n        'farm_context': {'crop': 'tomato', 'area_ha': 2.0},\n        'max_tokens': 200\n    }\n)\ndata = response.json()\nprint(f\"{data['content']} ({data['latency_ms']}ms)\")\n```\n\n---\n\n## ⚡ Multi-Turn Conversation Pattern\n\n```javascript\nconst messages = [];\n\nasync function chat(userMsg) {\n  const response = await fetch('https://uniphy-farm-layout-model.hf.space/api/v1/llm/chat', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({\n      content: userMsg,\n      conversation_history: messages,  // Pass history\n      farm_context: { crop: 'tomato', area_ha: 2.0 }\n    })\n  });\n  const { content } = await response.json();\n  \n  // Add to history\n  messages.push({ role: 'user', content: userMsg });\n  messages.push({ role: 'assistant', content });\n  \n  return content;\n}\n\nawait chat('What is drip irrigation?');\nawait chat('Can I use it for peppers?');  // Uses full conversation history\n```\n\n---\n\n## 🌾 Farm Context Fields\n\n```json\n{\n  \"farm_name\": \"Johnson Farm\",           // Name of the farm\n  \"crop\": \"tomato\",                     // tomato, pepper, lettuce, cucumber, orchard, generic\n  \"area_ha\": 2.5,                       // Farm area in hectares\n  \"design_summary\": { }                 // From /rest/v1/design (optional)\n}\n```\n\n---\n\n## 🔍 Status Codes\n\n| Code | Meaning |\n|------|----------|\n| 200 | Success |\n| 422 | Validation error (invalid context, oversized message) |\n| 500 | Inference failed (LLM backend error) |\n| 503 | Service unavailable (HF_TOKEN not set) |\n\n---\n\n## ⚙️ Configuration\n\nThe Space needs `HF_TOKEN` environment variable for LLM inference:\n\n1. Get token: https://huggingface.co/settings/tokens (read-only)\n2. Add to Space secrets: https://huggingface.co/spaces/Uniphy/farm-layout-model/settings\n3. Name it `HF_TOKEN`\n\n---\n\n## 📊 Performance\n\n- **Typical latency:** 1.5–3 seconds (100–200 tokens)\n- **First request:** May take 5–10s (model loading)\n- **Rate limit:** HuggingFace free tier limits\n- **Batch efficiency:** More efficient than individual requests\n\n---\n\n## 🐛 Troubleshooting\n\n**503 Service Unavailable:** HF_TOKEN missing or invalid\n- Check Space secrets configuration\n- Verify token at https://huggingface.co/settings/tokens\n\n**504 Timeout:** Model loading or HF API slow\n- Retry after a few seconds\n- Reduce `max_tokens` to speed up\n\n**422 Validation Error:** Invalid request\n- Check message length (max 2000 chars)\n- Validate context via `/validate-context` endpoint\n- Review `/docs` for schema\n\n---\n\n## 📖 Full Documentation\n\n- **Detailed API specs:** [LLM_API_DOCS.md](./LLM_API_DOCS.md)\n- **Deployment & setup:** [DEPLOYMENT.md](./DEPLOYMENT.md)\n- **Local testing:** [test_llm_api.py](./test_llm_api.py)\n- **Implementation:** [llm_api.py](./llm_api.py)\n\n---\n\n## 🔗 Links\n\n- **HF Space:** https://huggingface.co/spaces/Uniphy/farm-layout-model\n- **API Base:** https://uniphy-farm-layout-model.hf.space\n- **API Docs:** https://uniphy-farm-layout-model.hf.space/docs\n- **GitHub:** https://hf.co/spaces/Uniphy/farm-layout-model (code)\n"