Initial commit: nick docs

03 - API Reference/AI API.md

@@ -0,0 +1,118 @@
+---
+title: AI API
+tags: [api, ai, reference]
+---
+
+# AI API
+
+Endpoints live under `/api/ai/*`. The router is [`backend/src/services/ai/aiRoutes.ts`](../../backend/src/services/ai/aiRoutes.ts) and delegates to [`aiController`](../../backend/src/services/ai/aiController.ts), which wraps the OpenAI SDK.
+
+The AI service is intentionally generic — there are no resource-specific endpoints (no "generate product description" route). Instead, four general-purpose endpoints (`generate`, `analyze`, `translate`, `assist`) accept a `purpose` field that the controller maps to a system prompt template. The frontend uses these for:
+
+- Product description generation (purpose: `description`)
+- Content moderation (purpose: `moderation` on `/analyze`)
+- Product recommendations (purpose: `recommend` on `/generate`)
+- In-app helper (`/assist`)
+
+> Note: the router currently exposes these endpoints **without** `authenticateToken`. Front-end usage assumes the user is logged in. If you need to add auth, do it in the router. OpenAI cost-protection and rate-limiting are handled inside `aiController` via the Redis-backed `rateLimitService`.
+
+## Endpoints
+
+### POST /api/ai/generate
+
+**Description:** Generate free-form text. Used for product descriptions, marketing copy, recommendation rationales.
+**Auth required:** No (intended for authenticated frontends)
+**Request body:**
+```ts
+{
+  prompt: string;
+  purpose?: "description" | "recommend" | "summary" | "generic";   // default "generic"
+  context?: Record<string, unknown>;       // injected into the system prompt
+  maxTokens?: number;                      // default 512, capped server-side
+  temperature?: number;                    // 0..2, default 0.7
+  language?: "en" | "fa" | "ar";           // default "en"
+}
+```
+**Response 200:**
+```json
+{
+  "success": true,
+  "data": {
+    "text": "...",
+    "model": "gpt-4o-mini",
+    "tokensUsed": { "prompt": 120, "completion": 340, "total": 460 }
+  }
+}
+```
+**Errors:** `400` invalid params, `429` quota exceeded, `502` upstream OpenAI error.
+
+### POST /api/ai/analyze
+
+**Description:** Analyze a piece of text. Used for moderation (flag offensive content), sentiment, keyword extraction.
+**Auth required:** No
+**Request body:**
+```ts
+{
+  text: string;
+  purpose?: "moderation" | "sentiment" | "keywords" | "summary";   // default "moderation"
+  language?: "en" | "fa" | "ar";
+}
+```
+**Response 200 (moderation example):**
+```json
+{
+  "success": true,
+  "data": {
+    "purpose": "moderation",
+    "flagged": false,
+    "categories": { "hate": 0.001, "harassment": 0.0 },
+    "suggestion": null
+  }
+}
+```
+**Response 200 (sentiment example):**
+```json
+{ "success": true, "data": { "purpose": "sentiment", "score": 0.62, "label": "positive" } }
+```
+
+### POST /api/ai/translate
+
+**Description:** Translate `text` between languages.
+**Auth required:** No
+**Request body:**
+```ts
+{
+  text: string;
+  from?: "en" | "fa" | "ar" | "auto";    // default "auto"
+  to: "en" | "fa" | "ar";
+}
+```
+**Response 200:** `{ success, data: { translated: "...", detectedFrom: "en" } }`
+
+### POST /api/ai/assist
+
+**Description:** In-app conversational assistant. Maintains short-term context per call (the client passes prior turns explicitly).
+**Auth required:** No
+**Request body:**
+```ts
+{
+  messages: Array<{ role: "user" | "assistant" | "system"; content: string }>;
+  purpose?: "help" | "search" | "navigate";    // tunes the system prompt
+  context?: { userId?: string; route?: string; locale?: string };
+}
+```
+**Response 200:** `{ success, data: { reply: { role: "assistant", content: "..." }, tokensUsed } }`
+
+## Configuration
+
+The OpenAI client is configured via env:
+
+- `OPENAI_API_KEY` (required)
+- `OPENAI_MODEL` (default `gpt-4o-mini`)
+- `OPENAI_BASE_URL` (override for self-hosted proxies)
+
+## Related
+
+- [[AI Integration]]
+- [[Moderation Pipeline]]
+- [[Rate Limiting]]