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\nbash\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\nbash\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\nRequest 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\nResponse: 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\nbash\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\nResponse: {\"valid\": true, \"warnings\": [], \"errors\": []}\n\n---\n\n### POST /api/v1/llm/chat/batch\nBulk requests (max 10). Each request independent.\n\nbash\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\nResponse: Array of responses in same order as requests\n\n---\n\n## 💻 Language Examples\n\n### JavaScript\njavascript\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\npython\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\njavascript\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\njson\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\n503 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\n422 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\n- Deployment & setup: DEPLOYMENT.md\n- Local testing: test_llm_api.py\n- Implementation: 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"