> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freeplay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizing Principles

> Understand the core namespaces and hierarchy that structure the Freeplay SDK.

The Freeplay SDK is organized around a clear hierarchy of entities that map to how generative AI applications work in practice. Understanding this structure will help you integrate Freeplay effectively.

## The Observability Hierarchy

Freeplay organizes your LLM application observability data in a three-level hierarchy:

```
Project
  └── Session (a complete user interaction, multi-turn conversation, or instance of your application running)
        └── Trace (optional grouping of related completions; required for complex agents)
              └── Completion (a single LLM call)
```

* **Completions** are atomic LLM calls -- a prompt sent to a model and its response.
* **Traces** optionally group related completions, such as multiple LLM calls that power a single agent action. When building agents, Freeplay expects you to *name* traces to group related agent runs.
* **Sessions** contain all completions and traces for a logical user interaction (e.g., a chat conversation). You can choose to provide a session ID when recording completions. Sessions are created automatically if they don't exist.

For more detail on when to use traces vs. sessions, see [Sessions, Traces, and Completions](/core-concepts/observability/sessions-traces-and-completions).

## SDK Namespaces

All SDK operations are accessed through the Freeplay client object. The SDK is organized into namespaces that correspond to the core entities in Freeplay:

| Namespace                  | Purpose                                                     | Documentation                                                |
| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
| `client.sessions`          | Create and manage sessions to group related completions     | [Sessions](/freeplay-sdk/sessions)                           |
| `client.traces`            | Create traces to group related completions within a session | [Traces](/freeplay-sdk/traces)                               |
| `client.recordings`        | Record completions to Freeplay for observability            | [Recording Completions](/freeplay-sdk/recording-completions) |
| `client.customer_feedback` | Log user feedback associated with completions               | [Customer Feedback](/freeplay-sdk/customer-feedback)         |
| `client.prompts`           | Fetch and format prompt templates from Freeplay             | [Prompts](/freeplay-sdk/prompts)                             |
| `client.test_runs`         | Execute batch tests using saved datasets                    | [Test Runs](/freeplay-sdk/test-runs)                         |

<Tip>
  Some SDKs use camelCase (TypeScript, Java, Kotlin) rather than snake\_case (Python) for method names, following language conventions. The functionality is identical across languages.
</Tip>

## Common Integration Flow

A basic integration follows this pattern:

1. **Fetch a specific version of a prompt template** from Freeplay with variables inserted by your code
2. **Call your LLM provider** (OpenAI, Anthropic, etc.) with the formatted prompt
3. **Record the completion** back to Freeplay for observability

```python python theme={null}
# 1. Fetch and format the prompt
formatted_prompt = fp_client.prompts.get_formatted(
    project_id=project_id,
    template_name="my-prompt",
    environment="prod",
    variables={"question": user_question}
)

# 2. Call your LLM provider
response = openai_client.chat.completions.create(
    model=formatted_prompt.prompt_info.model,
    messages=formatted_prompt.llm_prompt,
    **formatted_prompt.prompt_info.model_parameters
)

# 3. Record to Freeplay
session = fp_client.sessions.create()
fp_client.recordings.create(RecordPayload(
    project_id=project_id,
    all_messages=formatted_prompt.all_messages({
        'role': response.choices[0].message.role,
        'content': response.choices[0].message.content
    }),
    session_info=session.session_info,
    prompt_version_info=formatted_prompt.prompt_info,
    # ... additional parameters
))
```

For complete examples, see the [Recording Completions](/freeplay-sdk/recording-completions) page or browse [Code Recipes](/developer-resources/recipes/overview).

## Choosing Your Integration Approach

Freeplay offers multiple ways to integrate, depending on your needs:

| Approach                                                                 | Language                | Best For                             | Observability | Prompt Management |
| ------------------------------------------------------------------------ | ----------------------- | ------------------------------------ | ------------- | ----------------- |
| [**Freeplay SDK**](/freeplay-sdk/setup)                                  | Python, TS, Java/Kotlin | Direct integration with full control | ✅             | ✅                 |
| [**LangGraph**](/developer-resources/integrations/langgraph)             | Python                  | LangGraph agent workflows            | ✅ Auto        | ✅                 |
| [**Vercel AI SDK**](/developer-resources/integrations/vercel-ai-sdk)     | TypeScript              | TypeScript/JS AI applications        | ✅ Auto        | ✅                 |
| [**Google ADK**](/developer-resources/integrations/adk)                  | Python                  | Google Agent Development Kit         | ✅ Auto        | ✅                 |
| [**OpenTelemetry**](/developer-resources/integrations/tracing-with-otel) | Any                     | Any framework, standard tracing      | ✅             | ❌                 |
| [**HTTP API**](/api-reference)                                           | Any                     | Custom implementations, automation   | ✅             | ✅                 |

<Note>
  OpenTelemetry integration provides observability only. For prompt management with OTel-traced applications, use the Freeplay SDK alongside your OTel instrumentation.
</Note>

For framework integrations, see [AI Framework Integrations](/developer-resources/integrations/langgraph).

## Production Best Practices

Many Freeplay customers configure different client setups for different environments:

* **Development/Staging**: Fetch prompts from the Freeplay server for rapid iteration
* **Production**: Use [Prompt Bundling](/core-concepts/prompt-management/prompt-bundling) to read prompts from local files for zero latency and resilience

See [Prompt Bundling](/core-concepts/prompt-management/prompt-bundling) for implementation details.

## Next Steps

**Getting started:**

* [Setup](/freeplay-sdk/setup) - Install and configure the SDK
* [Prompts](/freeplay-sdk/prompts) - Fetch and format prompt templates
* [Recording Completions](/freeplay-sdk/recording-completions) - Log LLM interactions

**When you need more control:**

* [Sessions](/freeplay-sdk/sessions) - Explicitly create sessions with custom metadata (sessions are auto-created if you don't)
* [Traces](/freeplay-sdk/traces) - Group related completions for agent workflows with multiple LLM calls or tool invocations