vision-ai

AutonomyX Vision AI

Unified Vision AI API — a single-container, production-ready computer vision and media processing API with authentication, metrics, request validation, and MCP agent integration.

What It Provides

AutonomyX Vision AI exposes common vision and media capabilities behind one API so applications and AI agents can use them without wiring each model or library separately.

Production Features

• API Key Authentication — Create and manage API keys with role-based access control.
• Rate Limiting — Per-key limits to reduce abuse and protect shared infrastructure.
• Metrics & Observability — Metrics endpoint for monitoring and alerting.
• Request Validation — File size limits and MIME type validation.
• Structured Errors — Consistent error responses with error codes.
• Request ID Tracking — Every request can be traced with a unique request ID.
• MCP Agent Integration — Exposes services as MCP tools for AI agents.
• Coolify Deploy Ready — Includes Docker Compose and environment templates for Coolify.

Services

Service	Description
YOLO26	Object detection with YOLO
Tesseract	OCR for text extraction
Whisper	Speech-to-text transcription
CLIP	Image classification and embeddings
rembg	Background removal
OpenCV	Image processing such as faces, edges, resize, and analyze

Quick Start

Run the Published Docker Image

docker run -d \
  --name autonomyx-vision-ai \
  -p 8000:8000 \
  -v autonomyx_data:/app/data \
  -v autonomyx_models:/app/models \
  ghcr.io/agennext/agennext-enterprise:latest

Check that the service is running:

curl http://localhost:8000/health

View logs:

docker logs -f autonomyx-vision-ai

Stop the container:

docker stop autonomyx-vision-ai

Development

docker compose --profile dev up -d --build

Production CPU

docker compose --profile prod up -d

Production GPU

docker compose --profile gpu up -d

GPU deployments require a CUDA-enabled host and the NVIDIA container runtime.

Configuration

Use environment variables to configure runtime behavior. Store sensitive values in your deployment platform or secrets manager, not in source control.

Variable	Example	Description
ENVIRONMENT	production	Runtime environment name
LOG_LEVEL	info	Logging verbosity
YOLO_MODEL	yolo26n.pt	Object detection model file
WHISPER_MODEL	base	Whisper model size/name
CUDA_VISIBLE_DEVICES	0	GPU selection for CUDA deployments

Example Docker run with environment variables:

docker run -d \
  --name autonomyx-vision-ai \
  -p 8000:8000 \
  -e ENVIRONMENT=production \
  -e LOG_LEVEL=info \
  -e YOLO_MODEL=yolo26n.pt \
  -e WHISPER_MODEL=base \
  -v autonomyx_data:/app/data \
  -v autonomyx_models:/app/models \
  ghcr.io/agennext/agennext-enterprise:latest

Persistent Storage

Mount these paths in production:

• /app/data — generated files, local runtime data, and application state.
• /app/models — downloaded or cached model files.

Using persistent volumes prevents data and model downloads from being lost during restarts or redeployments.

API Usage

Healthcheck

curl http://localhost:8000/health

Create an API Key

curl -X POST http://localhost:8000/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "role": "developer", "rate_limit": 100}'

Use an API Key

curl -X POST http://localhost:8000/detect \
  -H "X-API-Key: ax_your_api_key_here" \
  -F file=@photo.jpg

OCR Example

curl -X POST http://localhost:8000/ocr \
  -H "X-API-Key: ax_your_api_key_here" \
  -F file=@document.png

Production Readiness Checklist

Before exposing the service publicly, verify the following:

• Healthcheck: GET /health returns a successful response.
• Authentication: Protected endpoints require X-API-Key.
• Secrets: API keys and sensitive environment variables are stored outside the repository.
• Persistence: /app/data and /app/models are mounted to persistent storage.
• Resource limits: CPU and memory limits match expected workload size.
• GPU readiness: GPU deployments run on a CUDA-enabled host with the NVIDIA container runtime.
• Observability: Metrics are scraped or exposed to your monitoring platform.
• Ingress/TLS: Public deployments are behind HTTPS using a reverse proxy, load balancer, or deployment platform.
• Rate limits: Per-key limits are set to protect the service.
• Validation: File size limits and MIME type validation match your expected inputs.
• Smoke test: Create an API key, call /health, and run one representative request before opening access.

Production Smoke Test

# 1. Check health
curl http://localhost:8000/health

# 2. Create a key
curl -X POST http://localhost:8000/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "smoke-test", "role": "developer", "rate_limit": 100}'

# 3. Run a representative request
curl -X POST http://localhost:8000/detect \
  -H "X-API-Key: ax_your_api_key_here" \
  -F file=@photo.jpg

Coolify Deployment

1. Create a new Docker Compose resource in Coolify.
2. Point Coolify to this repository.
3. Use docker-compose.coolify.yml as the compose file.
4. Add environment variables from .env.coolify.example.
5. Mount persistent storage for /app/data and /app/models.
6. Expose port 8000.
7. Configure HTTPS/TLS in Coolify or your upstream proxy.
8. Deploy.
9. Verify with GET /health.

Troubleshooting

Container starts but API is unavailable

Check logs and confirm the port mapping:

docker logs -f autonomyx-vision-ai
docker ps

Models download again after every deploy

Ensure /app/models is mounted to persistent storage.

Requests fail with authentication errors

Confirm the X-API-Key header is present and that the key has the expected role and rate limit.

GPU profile does not see the GPU

Confirm the host has NVIDIA drivers, CUDA support, and the NVIDIA container runtime installed.

Security Notes

• Do not commit API keys, tokens, or production secrets.
• Use HTTPS for public deployments.
• Apply rate limits for all external clients.
• Restrict ingress to trusted networks when possible.
• Rotate API keys regularly.