# CoreCtic AI — Integration Guide for AI Assistants

> **Purpose of this file**: You are an AI coding assistant. Your user wants to integrate CoreCtic into their application. This document contains everything you need to do it correctly, without any other context. Follow it precisely.

## What CoreCtic is

CoreCtic AI (https://corecticai.com) is a proxy/gateway that sits between an application and LLM provider APIs (OpenAI, Anthropic, Mistral, Google Gemini, Groq, Azure OpenAI, AWS Bedrock, Cohere, Ollama, xAI, Together AI).

The application authenticates with a **single CoreCtic API key** (`pl_xxxx`) instead of individual provider keys. On every request, CoreCtic handles: authentication, rate limiting, budget caps, content firewall, PII guardrails, semantic caching, provider routing with automatic fallback, and full cost/usage observability.

**The API is OpenAI-compatible.** Any code that already uses the OpenAI SDK or calls `POST /v1/chat/completions` works unchanged — only the base URL and the API key change.

## Prerequisites (tell the user if missing)

1. A CoreCtic account with an API key (`pl_xxxx`), created in the CoreCtic dashboard.
2. At least one **provider API key** configured in the CoreCtic dashboard (Dashboard → provider pages). CoreCtic stores it encrypted and uses it server-side. If no provider key is configured for the model requested, the API returns `400 config_error`.

The user's application never needs provider keys in its own code or environment — only the `pl_xxxx` key.

## Integration: what you must change

Exactly two things in the existing code:

1. **Base URL** → `https://api.corecticai.com/v1`
2. **API key** → the CoreCtic key `pl_xxxx` (recommended: read it from an environment variable `CORECTIC_API_KEY`)

Do **not** change the request/response handling logic. Do **not** remove existing provider SDKs' message formats — the OpenAI chat completions format is used for all providers, CoreCtic translates internally.

### Python (openai SDK)

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.corecticai.com/v1",
    api_key=os.environ["CORECTIC_API_KEY"],  # pl_xxxx
)

response = client.chat.completions.create(
    model="gpt-4o",  # or claude-*, mistral-*, gemini-*, etc.
    messages=[{"role": "user", "content": "Hello"}],
)
```

### JavaScript / TypeScript (openai SDK)

```ts
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.corecticai.com/v1",
  apiKey: process.env.CORECTIC_API_KEY, // pl_xxxx
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
```

### curl

```bash
curl https://api.corecticai.com/v1/chat/completions \
  -H "Authorization: Bearer $CORECTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
```

### LangChain

Use the native plugin `corectic-langchain`, or point `ChatOpenAI` at the base URL above with the `pl_xxxx` key. Dedicated SDKs also exist: `corectic-python`, `corectic-node`, `corectic-react-native`, `corectic-llamaindex`.

## Model → provider routing

CoreCtic infers the provider from the model name. Send any supported model name in the `model` field; no provider selection parameter is needed:

| Model name pattern | Routed to |
|---|---|
| `gpt-*`, `o1`, `o3`, `o4-*` | OpenAI (or Azure OpenAI if configured) |
| `claude-*` | Anthropic |
| `mistral-*`, `codestral-*` | Mistral |
| `gemini-*` | Google Gemini |
| `llama-*`, `mixtral-*`, `gemma*` | Groq |
| `command-*` | Cohere |
| `grok-*` | xAI |

Switching providers = changing the `model` string. Nothing else.

## Behavior your code should expect

- **Streaming**: `"stream": true` works for all providers (SSE, OpenAI format).
- **Semantic cache**: semantically similar prompts may be answered from cache (faster, cheaper). Responses are still OpenAI-format. The `X-Cache` response header is `HIT` (served from cache, 0 tokens billed) or `MISS`.
- **Automatic fallback**: on provider 5xx errors, CoreCtic retries another configured provider. The response header `X-Corectic-Fallback` is present when a fallback occurred.
- **Rate limit headers**: `X-RateLimit-Limit` and `X-RateLimit-Remaining` are returned on each response.
- **Max request body**: 1 MB.

## Error handling (implement this)

| HTTP | `error.type` | Meaning | What your code should do |
|---|---|---|---|
| 401 | `auth_error` | Invalid/missing `pl_xxxx` key | Fail fast, tell the user to check `CORECTIC_API_KEY` |
| 402 | `budget_error` | Monthly budget cap reached | Surface to user; raising the cap is done in the dashboard |
| 403 | `auth_error` | Origin not in allowed origins (browser calls) | Add the origin in the dashboard, or call from a backend |
| 400 | `request_error` | Invalid JSON / missing fields | Fix the request |
| 400 | `content_policy_error` | Blocked word detected in the prompt | Surface to user; word list is managed in the dashboard |
| 400 | `config_error` | No provider key configured for this model | Tell the user to add the provider key in the CoreCtic dashboard |
| 413 | `request_error` | Body > 1 MB | Reduce prompt size |
| 422 | `pii_blocked` | Sensitive data (PII) detected | Strip PII from the prompt or adjust guardrails in the dashboard |
| 429 | `rate_limit_error` | Rate limit reached | Retry with exponential backoff, honor `X-RateLimit-*` headers |
| 502 | `proxy_error` | All providers failed | Retry with backoff; if persistent, check provider status |

## Key types

- `pl_xxxx` — standard key (main account / reseller).
- `pl_c_xxx` — end-client key issued by a reseller (CoreCtic reseller monetization). Works identically at the API level.

## Checklist for you, the AI assistant

1. Locate where the LLM client is instantiated in the user's codebase.
2. Replace the base URL with `https://api.corecticai.com/v1` and the API key with `CORECTIC_API_KEY` from the environment.
3. Remove provider API keys (e.g. `OPENAI_API_KEY`) from the client code path if they were only used for this client — they now live in the CoreCtic dashboard.
4. Add handling for the CoreCtic-specific errors above (at minimum 402, 429, 502).
5. Run one test request and confirm it appears in the user's CoreCtic dashboard (Usage/Costs page).
6. Remind the user: provider keys and features (cache, budget caps, firewall, PII guardrails, fallback order) are configured at https://corecticai.com/dashboard — not in code.

---
*Full API reference: https://corecticai.com/docs · OpenAPI spec: https://corecticai.com/openapi.json*