Add deployment guide for HuggingFace Space API access

- Public web URL for developers: https://uniphy-farm-layout-model.hf.space
- API endpoints documentation with cURL, Python, JavaScript examples
- Environment setup (HF_TOKEN configuration)
- Troubleshooting guide for common issues
- Interactive API docs at /docs endpoint
- Rate limits and quotas info
- Local development instructions

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

DEPLOYMENT.md

@@ -0,0 +1 @@
+# Farm Layout Model API - Deployment & Access Guide\n\n## HuggingFace Space\n\nThe API is deployed as a public HuggingFace Space:\n\n**Web URL:** `https://huggingface.co/spaces/Uniphy/farm-layout-model`\n\n**API Base URL:** `https://uniphy-farm-layout-model.hf.space`\n\n### Environment Configuration\n\nThe Space requires a HuggingFace API token for LLM inference:\n\n1. Go to [HF Settings → Tokens](https://huggingface.co/settings/tokens)\n2. Create a **read-only** token\n3. Add to Space secrets at `https://huggingface.co/spaces/Uniphy/farm-layout-model/settings` under \"Repository secrets\"\n4. Name it `HF_TOKEN`\n\nThe Space will automatically read `HF_TOKEN` from environment variables and pass it to the LLM inference layer.\n\n---\n\n## API Endpoints\n\nAll endpoints are available at `https://uniphy-farm-layout-model.hf.space/api/v1/llm/`\n\n### 1. Health Check\n```bash\ncurl https://uniphy-farm-layout-model.hf.space/api/v1/llm/health\n```\n\n**Response:**\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### 2. Chat Inference\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 should tomatoes get weekly?\",\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**Response:**\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\": 0\n  }\n}\n```\n\n### 3. Validate Context\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      \"farm_name\": \"Smith Farm\",\n      \"crop\": \"lettuce\",\n      \"area_ha\": 0.5\n    }\n  }'\n```\n\n**Response:**\n```json\n{\n  \"valid\": true,\n  \"warnings\": [],\n  \"errors\": []\n}\n```\n\n### 4. Batch Chat\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    {\"content\": \"What is emitter spacing?\", \"farm_context\": {\"crop\": \"tomato\"}}\n  ]'\n```\n\n---\n\n## Usage Examples\n\n### JavaScript/Fetch\n\n```javascript\nconst BASE_URL = 'https://uniphy-farm-layout-model.hf.space';\n\n// Health check\nconst health = await fetch(`${BASE_URL}/api/v1/llm/health`).then(r => r.json());\nconsole.log(`API Status: ${health.status}`);\n\n// Chat with farm context\nconst response = await fetch(`${BASE_URL}/api/v1/llm/chat`, {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    content: 'How often should I water tomatoes?',\n    farm_context: {\n      farm_name: 'Johnson Farm',\n      crop: 'tomato',\n      area_ha: 2.5\n    },\n    max_tokens: 200\n  })\n});\n\nconst { content, latency_ms } = await response.json();\nconsole.log(`Response (${latency_ms}ms): ${content}`);\n```\n\n### Python\n\n```python\nimport requests\n\nBASE_URL = 'https://uniphy-farm-layout-model.hf.space'\n\n# Health check\nhealth = requests.get(f'{BASE_URL}/api/v1/llm/health').json()\nprint(f\"API Status: {health['status']}\")\n\n# Chat with farm context\nresponse = requests.post(\n    f'{BASE_URL}/api/v1/llm/chat',\n    json={\n        'content': 'How much water should I apply?',\n        'farm_context': {\n            'farm_name': 'Johnson Farm',\n            'crop': 'tomato',\n            'area_ha': 2.5\n        },\n        'max_tokens': 200\n    }\n)\n\ndata = response.json()\nprint(f\"Response ({data['latency_ms']}ms): {data['content']}\")\n```\n\n### cURL\n\n```bash\n# Health check\ncurl https://uniphy-farm-layout-model.hf.space/api/v1/llm/health | jq\n\n# Chat\ncurl -X POST https://uniphy-farm-layout-model.hf.space/api/v1/llm/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"What is drip irrigation?\", \"max_tokens\": 150}' | jq '.content'\n```\n\n---\n\n## Interactive API Documentation\n\nOnce the Space is running, access interactive Swagger/OpenAPI docs:\n\n```\nhttps://uniphy-farm-layout-model.hf.space/docs\n```\n\nThis page auto-generated by FastAPI shows:\n- All available endpoints\n- Request/response schemas\n- Try-it-out forms to test directly\n\n---\n\n## Design API (Bonus)\n\nThe Space also exposes the design endpoint at `/rest/v1/design`:\n\n```bash\ncurl -X POST https://uniphy-farm-layout-model.hf.space/rest/v1/design \\\n  -H \"Content-Type: application/json\" \\\n  -d '@design_request.json'\n```\n\nSee `rest_api.py` and `LLM_API_DOCS.md` for details.\n\n---\n\n## Rate Limits & Quotas\n\n- **HuggingFace Inference API:** Subject to HF's free tier rate limits\n- **Batch requests:** Max 10 per request\n- **Content size:** Max 2000 characters per message\n- **Response tokens:** Max 1024\n\nFree tier may have queuing during peak hours. For production use, consider:\n1. Upgrading to HF's paid Inference API\n2. Self-hosting on your own infrastructure\n3. Using a local LLM via `ollama` or similar\n\n---\n\n## Troubleshooting\n\n### 503 Service Unavailable\n\n**Cause:** HF_TOKEN not configured or invalid\n\n**Solution:**\n1. Check Space secrets at Settings → Repository secrets\n2. Verify `HF_TOKEN` is set and valid\n3. Test token at https://huggingface.co/settings/tokens\n\n### 504 Gateway Timeout\n\n**Cause:** Model is loading or HF Inference API is slow\n\n**Solution:**\n1. Wait a few seconds and retry\n2. Check https://status.huggingface.co for service status\n3. Try reducing `max_tokens` to speed up inference\n\n### 422 Validation Error\n\n**Cause:** Invalid request format\n\n**Solution:**\n1. Check request matches the schema (see `/docs`)\n2. Validate farm context via `/api/v1/llm/validate-context`\n3. Check message length (max 2000 chars)\n\n---\n\n## Local Development\n\nTo test locally before pushing to the Space:\n\n```bash\n# Install dependencies\npip install -r requirements.txt\n\n# Set HuggingFace token\nexport HF_TOKEN=hf_your_token_here\n\n# Run the server\npython app.py\n\n# Test endpoints\npython test_llm_api.py\n```\n\nServer runs at `http://localhost:7860`\n\n---\n\n## Monitoring & Logging\n\nHuggingFace Spaces logs are available at:\n\n```\nhttps://huggingface.co/spaces/Uniphy/farm-layout-model/logs\n```\n\nCheck logs to debug issues or monitor usage.\n\n---\n\n## Contact & Support\n\nFor issues or questions:\n1. Check [HF Spaces docs](https://huggingface.co/docs/hub/spaces)\n2. Review `LLM_API_DOCS.md` for detailed endpoint specs\n3. Run `python test_llm_api.py` locally to validate your requests\n"