# QFOXAI AGENTS.md

This file is for AI coding agents integrating QFOXAI into customer projects.

## Mission

Integrate QFOXAI as an OpenAI-compatible provider with safe server-side key handling, clear quota/error handling, and public QFOXAI model aliases.

## Required Environment Variables

```env
QFOXAI_API_KEY=qf_your_full_secret_key
QFOXAI_BASE_URL=https://qfoxai.com/v1
QFOXAI_MODEL=QFOXAI
```

## Integration Steps

1. Add the API key to server-side environment configuration.
2. Configure the OpenAI-compatible client base URL as `https://qfoxai.com/v1`.
3. Omit the model for key, project, smart-routing, and platform defaults, or fetch allowed aliases from `GET https://qfoxai.com/v1/models`.
4. Send chat requests to `/chat/completions` through the client library or HTTP backend.
5. Add quota-aware UI using `GET https://qfoxai.com/v1/key` and response headers.
6. Add retry/backoff for temporary service and rate-limit errors.
7. Log `X-QFOXAI-Request-ID` for support and troubleshooting.

## Do Not

- Do not put the full API key in browser JavaScript, mobile app bundles, or public repositories.
- Do not expose internal provider model names.
- Do not hard-code a private backend model. Use public aliases only.
- Do not describe QFOXAI as another provider. It is QFOXAI with OpenAI-compatible API shape.

## Best User Experience

- Add a settings page for API key, base URL, and model alias.
- Add a Test QFOXAI connection button.
- Show upgrade/renew prompts when quota is low or subscription is expired.
- Estimate before heavy jobs with `POST /v1/estimate` and show a friendly confirmation when usage is high.
- Surface friendly errors for invalid key, quota full, expired subscription, and temporary service unavailable.

## Helpful Links

- API docs: https://qfoxai.com/docs/api
- OpenAPI schema: https://qfoxai.com/openapi.json
- Markdown docs: https://qfoxai.com/docs.md
- Integrations: https://qfoxai.com/integrations
- Solutions: https://qfoxai.com/solutions
- Migration guides: https://qfoxai.com/migration-guides
- Benchmarks: https://qfoxai.com/benchmarks
- Partners: https://qfoxai.com/partners
- Trust: https://qfoxai.com/trust