docs(traceai): add Overview and Quickstart

src/pages/docs/traceai/index.mdx

@@ -0,0 +1,51 @@
+---
+title: "traceAI"
+description: "Future AGI's open-source SDK for tracing AI applications on OpenTelemetry"
+---
+
+traceAI is Future AGI's open-source SDK for tracing AI applications. It captures every LLM call, prompt, token count, retrieval step, and agent decision as structured OpenTelemetry spans, so you can see what your application did and where it went wrong.
+
+## In this page
+
+traceAI is a set of OpenTelemetry conventions and framework instrumentors. You add a few lines to an existing app, and each model, framework, and vendor call is mapped to a standard set of span attributes. The output is plain OpenTelemetry, so the spans land in Future AGI Observe natively, or in any OpenTelemetry-compatible backend.
+
+## What traceAI captures
+
+For every step of an AI application, traceAI records the data you need to debug it:
+
+- LLM calls, with the prompt, completion, model parameters, and token counts
+- Retrieval and vector database steps
+- Tool calls and agent decisions
+- Errors, latency, and streaming, at low overhead
+
+## Languages and frameworks
+
+traceAI ships one consistent API across four languages, with drop-in instrumentors for 50+ AI frameworks:
+
+- **Python** 3.10+
+- **TypeScript** 5.0+
+- **Java** 17+
+- **C#** on .NET
+
+Each framework has its own instrumentor package, so you install only what your stack uses. OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, and Bedrock are a few of the supported frameworks. The [integrations](/docs/integrations/traceai/openai) section lists every one.
+
+## How it fits with Observe
+
+traceAI is the instrumentation layer. It produces the spans; Future AGI Observe reads them.
+
+Because the output is standard OpenTelemetry, the same spans also work with Datadog, Grafana, Jaeger, or any other OpenTelemetry-compatible backend. There is no separate agent and no proprietary format to adopt.
+
+<Note>
+traceAI is open source under Apache 2.0. It is natively supported by Future AGI, but is not tied to it.
+</Note>
+
+## Keep exploring
+
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/docs/traceai/quickstart">
+    Install an instrumentor and send your first trace in about five minutes
+  </Card>
+  <Card title="Integrations" icon="plug" href="/docs/integrations/traceai/openai">
+    Browse the instrumentor for every supported framework
+  </Card>
+</CardGroup>

src/pages/docs/traceai/quickstart.mdx

@@ -0,0 +1,133 @@
+---
+title: "Quickstart"
+description: "Add traceAI to your app and send your first AI trace in about five minutes"
+---
+
+Add traceAI to an existing app and send your first trace in about five minutes, without changing your application logic.
+
+## In this page
+
+You will install a traceAI instrumentor, register a project, run one instrumented LLM call, and confirm the trace in Future AGI Observe. The same steps work for 50+ frameworks, so once one call is traced you have the pattern for the rest of your stack.
+
+## Prerequisites
+
+- A Future AGI account with your `FI_API_KEY` and `FI_SECRET_KEY` (Dashboard → Build → Keys)
+- Python 3.10 or later (or Node 18+ for the TypeScript path)
+- An OpenAI API key
+
+<Note>
+Pin each package to the version you test against, so a later release cannot change behavior under you
+</Note>
+
+## Steps
+
+<Steps>
+  <Step title="Install traceAI">
+    Install the core package and the instrumentor for the framework you use. This example uses OpenAI.
+
+    <CodeGroup titles={["Python", "JS/TS"]}>
+    ```bash Python
+    pip install fi-instrumentation-otel traceAI-openai
+    ```
+    ```bash JS/TS
+    npm install @traceai/fi-core @traceai/openai
+    ```
+    </CodeGroup>
+  </Step>
+
+  <Step title="Set your keys">
+    Read the keys from the environment, never hardcode them in source.
+
+    ```bash
+    export FI_API_KEY="your-futureagi-api-key"
+    export FI_SECRET_KEY="your-futureagi-secret-key"
+    export OPENAI_API_KEY="your-openai-api-key"
+    ```
+  </Step>
+
+  <Step title="Register a project and trace one call">
+    `register` returns a tracer provider. Set `project_type` to `OBSERVE`, attach the instrumentor, then call the model exactly as you normally would.
+
+    <CodeGroup titles={["Python", "JS/TS"]}>
+    ```python Python
+    from fi_instrumentation import register, Transport
+    from fi_instrumentation.fi_types import ProjectType
+    from traceai_openai import OpenAIInstrumentor
+    from openai import OpenAI
+
+    # Connect to Future AGI and create (or reuse) an Observe project
+    trace_provider = register(
+        project_type=ProjectType.OBSERVE,
+        project_name="my-first-project",
+        transport=Transport.GRPC,
+    )
+
+    # Auto-instrument OpenAI: every call is now traced
+    OpenAIInstrumentor().instrument(tracer_provider=trace_provider)
+
+    # Use OpenAI exactly as you normally would
+    client = OpenAI()
+    completion = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Write a one-sentence bedtime story about a unicorn."}],
+    )
+    print(completion.choices[0].message.content)
+    ```
+    ```typescript JS/TS
+    import { register, ProjectType } from "@traceai/fi-core";
+    import { OpenAIInstrumentation } from "@traceai/openai";
+    import { registerInstrumentations } from "@opentelemetry/instrumentation";
+    import OpenAI from "openai";
+
+    // Connect to Future AGI and create (or reuse) an Observe project
+    const traceProvider = register({
+      project_type: ProjectType.OBSERVE,
+      project_name: "my-first-project",
+    });
+
+    // Auto-instrument OpenAI: every call is now traced
+    registerInstrumentations({
+      instrumentations: [new OpenAIInstrumentation({})],
+      tracerProvider: traceProvider,
+    });
+
+    // Use OpenAI exactly as you normally would
+    const client = new OpenAI();
+    const completion = await client.chat.completions.create({
+      model: "gpt-4o",
+      messages: [{ role: "user", content: "Write a one-sentence bedtime story about a unicorn." }],
+    });
+    console.log(completion.choices[0].message.content);
+    ```
+    </CodeGroup>
+  </Step>
+
+  <Step title="Confirm the trace">
+    Open **Observe → my-first-project → Tracing**. Within a few seconds you will see one trace row with **status OK**, the **model**, the **latency**, and the **token count**. Click it to read the prompt, the completion, and the span timing.
+
+    <img src="/images/docs/observe/llm-tracing-overview.webp" alt="Observe trace explorer with one new OpenAI trace showing OK status, model, latency, and token columns" style={{ borderRadius: '5px' }} />
+    *Your request, now a trace. If the row is here with an OK status, instrumentation is working end to end*
+  </Step>
+</Steps>
+
+## Trace another framework
+
+Every framework follows the same shape. Swap the instrumentor package and its instrumentor class; the `register` step stays identical.
+
+- `traceAI-langchain` for LangChain
+- `traceAI-anthropic` for Anthropic
+- `traceAI-llamaindex` for LlamaIndex
+- `traceAI-crewai` for CrewAI
+
+The [integrations](/docs/integrations/traceai/openai) section has the exact import for each one.
+
+## Dive deeper
+
+<CardGroup cols={2}>
+  <Card title="traceAI" icon="circle-info" href="/docs/traceai">
+    What traceAI is and how it fits with Observe
+  </Card>
+  <Card title="Integrations" icon="plug" href="/docs/integrations/traceai/openai">
+    The instrumentor for every supported framework
+  </Card>
+</CardGroup>