ds-smart-farm-project/API_DOCUMENTATION.md

🚜 Smart Farm Photo Keyword Tagging AI - API Documentation

🌐 Web UI & API Overview

The Smart Farm AI system provides both a web interface and REST API for agricultural photo keyword generation.

🚀 Quick Start

# Start the web UI and API server
python3 start_ui.py

# Or manually start with uvicorn
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

Access Points:

• Web UI: http://localhost:8000
• API Docs: http://localhost:8000/docs (Swagger)
• Alternative Docs: http://localhost:8000/redoc
• System Status: http://localhost:8000/status

📋 API Endpoints

1. System Status

GET /status

Get current system status and capabilities.

Response:

{
  "status": "Operational",
  "model_loaded": true,
  "version": "1.0.0",
  "capabilities": [
    "Agricultural keyword generation",
    "Image title creation",
    "Quality validation",
    "Batch processing",
    "Agricultural distinctions (farmer vs rancher)",
    "Location extraction",
    "Performance metrics"
  ]
}

2. Single Image Analysis

POST /analyze/single

Analyze a single agricultural image for keywords and title.

Request:

• Content-Type: multipart/form-data
• Body: Image file (JPG, PNG, etc.)

Response:

{
  "filename": "farm_photo.jpg",
  "keywords": ["farmer", "corn", "field", "agriculture", "tractor"],
  "title": "Agricultural scene: Farmer working in corn field",
  "quality_score": 73.3,
  "processing_time": 2.5,
  "caption": "a farmer working in a corn field with a tractor"
}

cURL Example:

curl -X POST "http://localhost:8000/analyze/single" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@farm_photo.jpg"

3. Batch Image Analysis

POST /analyze/batch

Analyze multiple agricultural images in a single request.

Request:

• Content-Type: multipart/form-data
• Body: Multiple image files

Response:

{
  "total_images": 5,
  "successful": 5,
  "failed": 0,
  "results": [
    {
      "filename": "corn_field.jpg",
      "keywords": ["corn", "field", "agriculture", "farming"],
      "title": "Agricultural scene: Corn field at sunset",
      "quality_score": 80.0,
      "processing_time": 2.1,
      "caption": "a corn field at sunset"
    }
  ],
  "average_quality": 75.2,
  "total_processing_time": 12.5
}

cURL Example:

curl -X POST "http://localhost:8000/analyze/batch" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg" \
  -F "files=@photo3.jpg"

4. Demo with Sample Images

GET /demo

Run demonstration using existing sample agricultural images.

Response:

{
  "total_images": 7,
  "successful": 7,
  "failed": 0,
  "results": [
    {
      "filename": "agric-field8.png",
      "keywords": ["corn", "field", "agriculture", "farming", "rural"],
      "title": "Agricultural scene: A corn field with the sun setting",
      "quality_score": 73.3,
      "processing_time": 3.2,
      "caption": "a corn field with the sun setting in the background"
    }
  ],
  "average_quality": 65.2,
  "total_processing_time": 18.7
}

🎯 Quality Scoring

The system provides quality scores for generated keywords:

Score Range	Quality Level	Description
80-100	Excellent	High agricultural relevance, specific terms
60-79	Good	Relevant agricultural content, some generic terms
40-59	Fair	Basic agricultural recognition, needs improvement
0-39	Poor	Limited agricultural context, mostly generic

🔧 Agricultural Distinctions

The AI system automatically applies agricultural distinctions:

Farmer vs Rancher Logic

• Farmer: Detected when crops, grains, or cultivation mentioned
• Rancher: Detected when cattle, livestock, or grazing mentioned
• Dairy Farmer: Detected when milk, dairy, or Holstein mentioned
• Chicken Farmer: Detected when poultry, chickens, or eggs mentioned

Gender Identification

• Combines gender detection with agricultural roles
• Examples: "male farmer", "female rancher"

📊 Performance Metrics

Current System Performance:

• Processing Speed: ~3 seconds per image
• Batch Capability: 500+ images efficiently
• Quality Score: 65.2/100 average
• Scalability: 1000 images in ~50 minutes

🌐 Web UI Features

Interactive Interface

• Drag & Drop: Upload multiple images easily
• Real-time Processing: See results as they're generated
• Quality Visualization: Color-coded quality scores
• Demo Mode: Test with sample agricultural images

Visual Elements

• Green Theme: Agricultural color scheme
• Responsive Design: Works on desktop and mobile
• Progress Indicators: Loading states and progress bars
• Error Handling: Clear error messages and recovery

🔒 Error Handling

Common Error Responses

400 Bad Request

{
  "detail": "Invalid image format. Please upload JPG, PNG, or similar."
}

500 Internal Server Error

{
  "detail": "AI system not initialized"
}

404 Not Found

{
  "detail": "Sample images not found"
}

🧪 Testing the API

Python Example

import requests

# Test system status
response = requests.get("http://localhost:8000/status")
print(response.json())

# Analyze single image
with open("farm_photo.jpg", "rb") as f:
    files = {"file": f}
    response = requests.post("http://localhost:8000/analyze/single", files=files)
    print(response.json())

# Run demo
response = requests.get("http://localhost:8000/demo")
print(response.json())

JavaScript Example

// Analyze image with fetch API
const formData = new FormData();
formData.append('file', imageFile);

fetch('http://localhost:8000/analyze/single', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

🚀 Production Deployment

Docker Deployment

FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Environment Variables

# Optional configuration
export MODEL_PATH="/path/to/custom/model"  # Use custom trained model
export MAX_UPLOAD_SIZE="10MB"             # Limit upload size
export BATCH_SIZE_LIMIT="50"              # Limit batch processing

📈 Integration Examples

Stock Photo Platform Integration

# Example integration for stock photo workflow
import requests

def process_new_photos(photo_directory):
    files = []
    for photo in os.listdir(photo_directory):
        files.append(('files', open(os.path.join(photo_directory, photo), 'rb')))
    
    response = requests.post("http://localhost:8000/analyze/batch", files=files)
    results = response.json()
    
    # Update database with AI-generated keywords
    for result in results['results']:
        update_photo_keywords(result['filename'], result['keywords'])

Quality Control Workflow

# Filter high-quality results
def filter_high_quality_results(api_response):
    high_quality = []
    for result in api_response['results']:
        if result['quality_score'] >= 70:
            high_quality.append(result)
    return high_quality

🎯 Next Steps

1. Start the UI: python3 start_ui.py
2. Test with Demo: Click "Run Demo" button
3. Upload Your Photos: Drag and drop agricultural images
4. Integrate API: Use endpoints in your applications
5. Scale Up: Process your 30,000 photo dataset

---

Ready to demonstrate the system to your team! 🚜✨