Initial commit: add .gitignore and README

docs/openai_bridge.md

@@ -0,0 +1,166 @@
+# OpenAI Bridge for Cursor Composer
+
+The FusionAGI OpenAI bridge exposes an OpenAI-compatible API so you can use FusionAGI's Dvādaśa multi-agent system as a custom model in Cursor Composer and other OpenAI API consumers.
+
+## Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Cursor as Cursor Composer
+    participant API as FusionAGI API
+    participant Orch as Orchestrator
+    participant Heads as Dvādaśa Heads
+    participant Witness as Witness
+
+    Cursor->>API: POST /v1/chat/completions (messages)
+    API->>Orch: submit_task(goal from messages)
+    Orch->>Heads: run heads in parallel
+    Heads->>Witness: head outputs
+    Witness->>Orch: final_answer (synthesis)
+    Orch->>API: FinalResponse
+    API->>Cursor: OpenAI-format response (sync or SSE)
+```
+
+## Overview
+
+- **`GET /v1/models`** — Lists available models (returns `fusionagi-dvadasa`)
+- **`POST /v1/chat/completions`** — Chat completions (sync and streaming)
+
+The bridge translates OpenAI-style requests into FusionAGI tasks, runs the Dvādaśa heads and Witness, and returns responses in OpenAI format.
+
+## Quick Start
+
+### 1. Start the FusionAGI API
+
+```bash
+# Install with API support
+pip install -e ".[api]"
+
+# Start the server (use a real LLM adapter for production)
+uvicorn fusionagi.api.app:app --reload
+```
+
+The API runs at `http://localhost:8000` by default.
+
+### 2. Configure Cursor Composer
+
+1. Open **Cursor Settings** → **Models** (or equivalent for your Cursor version).
+2. Click **Add Custom Model** or configure an OpenAI-compatible endpoint.
+3. Set:
+   - **Name**: FusionAGI Dvādaśa
+   - **Base URL**: `http://localhost:8000/v1`
+   - **Model ID**: `fusionagi-dvadasa`
+   - **API Key**: Any string (e.g. `sk-fusionagi`) when auth is disabled
+   - **Context Length**: 128000 (or your preferred value)
+   - **Temperature**: 0.7
+
+4. Select FusionAGI as the model for Composer.
+
+### 3. Use with Composer
+
+Composer will send requests to FusionAGI. Each prompt is processed by the Dvādaśa heads (Logic, Research, Strategy, Security, Safety, etc.) and synthesized by the Witness into a single response.
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENAI_BRIDGE_MODEL_ID` | `fusionagi-dvadasa` | Model ID returned by `/v1/models` |
+| `OPENAI_BRIDGE_AUTH` | `disabled` | Set to `Bearer` to enable API key auth |
+| `OPENAI_BRIDGE_API_KEY` | (none) | Required when auth is enabled |
+| `OPENAI_BRIDGE_TIMEOUT_PER_HEAD` | `60` | Max seconds per head agent |
+
+### Authentication
+
+**Development (default):** Auth is disabled. Any request is accepted.
+
+**Production:** Enable Bearer auth:
+
+```bash
+export OPENAI_BRIDGE_AUTH=Bearer
+export OPENAI_BRIDGE_API_KEY=your-secret-key
+```
+
+Cursor must then send `Authorization: Bearer your-secret-key` with each request.
+
+## API Details
+
+### Chat Completions
+
+**Request (sync):**
+```json
+{
+  "model": "fusionagi-dvadasa",
+  "messages": [
+    {"role": "system", "content": "You are helpful."},
+    {"role": "user", "content": "What is the best architecture for X?"}
+  ],
+  "stream": false
+}
+```
+
+**Request (streaming):**
+```json
+{
+  "model": "fusionagi-dvadasa",
+  "messages": [{"role": "user", "content": "Explain Y"}],
+  "stream": true
+}
+```
+
+**Response (sync):** Standard OpenAI chat completion object with `choices[0].message.content` and `usage`.
+
+**Response (streaming):** Server-Sent Events (SSE) with `data:` lines containing OpenAI-format chunks, ending with `data: [DONE]`.
+
+### Message Translation
+
+The bridge converts OpenAI messages to a single prompt for Dvādaśa:
+
+- **System messages** — Prepended as context
+- **User/assistant turns** — Formatted as `[User]:` / `[Assistant]:` conversation
+- **Tool results** — Included as `[Tool name] returned: ...`
+
+### Models
+
+**Request:**
+```
+GET /v1/models
+```
+
+**Response:**
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "fusionagi-dvadasa",
+      "object": "model",
+      "created": 1704067200,
+      "owned_by": "fusionagi"
+    }
+  ]
+}
+```
+
+## Limitations
+
+- **Tool calling:** Not supported in v1. The bridge returns text-only responses. Cursor workflows that expect `tool_calls` in the model response will not work. MCP tools provided by Cursor may still be used based on model output text.
+- **Token counts:** Usage is estimated from character counts (chars/4 heuristic). Exact token counts require a tokenizer.
+- **Vision/multimodal:** Image content in messages is not supported.
+- **Latency:** Dvādaśa runs multiple heads in parallel plus Witness synthesis, which can be slower than a single LLM call.
+
+## Example: curl
+
+```bash
+# List models
+curl -X GET http://localhost:8000/v1/models
+
+# Chat completion (sync)
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "fusionagi-dvadasa",
+    "messages": [{"role": "user", "content": "What is 2+2?"}]
+  }'
+```