Proxy FastAPI pour cursor-agent

Summary

• Proxy FastAPI exposant cursor-agent via une API REST compatible OpenAI/ChatGPT.
• Permet d'utiliser cursor-agent avec clients OpenAI officiels et outils compatibles.
• Supporte mapping automatique des noms de modèles OpenAI/Anthropic vers modèles cursor-agent.
• Streaming SSE pris en charge; endpoints principaux: chat/completions, chat/completions-stream, models, health.

Architecture

• Flux: Client -> cursor-openai-proxy (FastAPI) -> cursor-agent (CLI/HTTP/Library) -> LLM.
• Proxy: authentification API_KEY, mapping modèles, formatage réponse OpenAI-compatible.
• cursor-agent: utilise CURSOR_API_KEY, supporte modes cli/http/library.
• LLM: GPT-5, Claude 4.5, Opus 4.1, Grok, etc.

Prérequis et Installation

• Prérequis: Python 3.8+, uv (gestionnaire), just (task runner), cursor-agent (ou mode HTTP).
• Installation recommandée: uv sync ou just install.
• Alternatives: création venv, activation, uv pip install -e .
• Docker: image installe cursor-agent automatiquement.

Configuration (.env)

• Méthodes: just setup-env, scripts/setup-env.sh, ou copie manuelle .env.example -> .env.
• Variables essentielles:
  • CURSOR_AGENT_MODE: cli / http / library.
  • CURSOR_AGENT_CLI_PATH (si CLI) ou CURSOR_AGENT_HTTP_URL (si HTTP).
  • API_KEY: protège le proxy (production).
• Nota: API_KEY protège le proxy, pas cursor-agent.

Modèles Supportés

• Supporte tous les modèles disponibles dans cursor-agent.
• Mapping automatique des alias OpenAI/Anthropic vers modèles natifs.

• Modèles natifs exemples: default, gpt-5, sonnet-4, sonnet-4-thinking.

Endpoints Principaux

• POST /v1/chat/completions : requêtes chat compatibles OpenAI.
• POST /v1/chat/completions-stream : streaming SSE.
• GET /v1/models : liste des modèles disponibles.
• GET /health : vérification de santé.

Utilisation et Commandes

• Démarrer serveur:
  • just dev (dev, reload, port 8001)
  • just run (production, port 8001)
  • uv run python main.py
  • ./run.sh ou uv run uvicorn main:app --host 0.0.0.0 --port 8001 --reload
  • Docker: just docker-build / just docker-up ou docker-compose up -d
• Documentation: /docs (Swagger UI), /redoc; just docs ouvre la doc.

Exemples d'Usage

• Exemple Python avec client OpenAI:
  • Configurer client OpenAI: base_url="http://localhost:8001/v1", api_key=ENV.
  • Utiliser model="gpt-4o" (mappé vers gpt-5) ou model="claude-3-5-sonnet-20241022" (mappé).
• Exemple d'objet réponse compatible OpenAI inclus (id, object, choices, usage).

Tests

• Architecture tests: unitaires, intégration local (port 8001), intégration Docker (port 8002), bash/curl.
• Commandes:
  • just test (unitaires), just test-cov, just test-watch.
  • just test-integration-local (~21s), just test-integration-docker (~39s).
  • just test-integration-all, just test-all.
• Ports: 8001 pour Python local, 8002 pour Docker.

Sécurité

• En production: activer API_KEY, rate limiting (middleware), validation des entrées, logging, HTTPS/TLS.
• Rate limiting désactivé par défaut (commenter/décommenter dans main.py).
• Voir DEPLOYMENT.md et SECURITY.md pour détails.

Decisions

• API conçue pour être entièrement compatible OpenAI afin d'utiliser clients existants.
• Mapping automatique des alias OpenAI/Anthropic vers modèles cursor-agent retenu.
• Support multi-mode pour cursor-agent: cli, http, library.

Action Items

• (immédiat – développeur) Configurer .env avec CURSOR_AGENT_MODE et API_KEY selon le déploiement.
• (avant release – équipe) Activer rate limiting et HTTPS pour production.
• (pré-merge – CI) Exécuter just test-integration-local puis just test-integration-docker.
• (optionnel – dev) Tester streaming SSE via /v1/chat/completions-stream.

Open Questions

• Comment gérer précision du comptage de tokens en production (intégrer tiktoken) ?
• Nécessité d'adapter le streaming simulé selon capacités réelles de cursor-agent ?
• Politique recommandée pour rotation/gestion des API_KEY côté proxy et cursor-agent ?