Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/ai-python/content/docs/basics/streaming.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -63,15 +63,15 @@ message.

## Generate without streamed events

Use `ai.experimental_generate` when you only need the complete message:
Use `ai.generate` when you only need the complete message:

```python
message = await ai.experimental_generate(model, messages)
message = await ai.generate(model, messages)
print(message.text)
```

The function accepts the same tools, output type, and request parameters as
`ai.stream`. It is experimental and may change or be removed.
`ai.stream`.

## Use structured output

Expand Down
15 changes: 7 additions & 8 deletions docs/ai-python/content/docs/basics/telemetry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@ and agent loop turn — as a tree of *spans*. You decide where the spans go:
export them to OpenTelemetry, send them to an observability vendor, or print
them to the terminal.

Telemetry lives in the `ai.experimental_telemetry` module. It is experimental
and is not part of the stable API. It may change or be removed.
Telemetry lives in the `ai.telemetry` module.

## Turn on tracing

Expand All @@ -34,7 +33,7 @@ exporter before running your agent:

```python
import ai
from ai.experimental_telemetry import otel
from ai.telemetry import otel
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
Expand All @@ -45,7 +44,7 @@ provider.add_span_processor(
OTLPSpanExporter(endpoint="http://127.0.0.1:4318/v1/traces")
)
)
ai.experimental_telemetry.register(otel.OtelAdapter(tracer_provider=provider))
ai.telemetry.register(otel.OtelAdapter(tracer_provider=provider))
```

Point the exporter at your collector. At application shutdown, call
Expand All @@ -62,7 +61,7 @@ with adapters.
```python
import ai

async with ai.experimental_telemetry.span("retrieval") as sp:
async with ai.telemetry.span("retrieval") as sp:
sp.set_attrs(query=query)
docs = await search(query)
sp.set_attrs(count=len(docs))
Expand Down Expand Up @@ -93,7 +92,7 @@ to pytest fixtures or FastAPI lifecycles.
```python
import ai

@ai.experimental_telemetry.adapter
@ai.telemetry.adapter
async def vendor(span):
with sdk.start_span(span.name) as v: # create a span before the loop
while (ev := (yield)) is not None: # process events coming from span.add_event()
Expand All @@ -102,7 +101,7 @@ async def vendor(span):
v.set_error(span.error.message)
v.update(output=span.data.model_dump(mode="json"))

ai.experimental_telemetry.register(vendor) # register custom adapter
ai.telemetry.register(vendor) # register custom adapter
```

The function runs once per span:
Expand All @@ -127,5 +126,5 @@ independently.
The module also has a low-level API, that can be useful for instrumenting complicated
cases such as durable execution. It provides more control over adapter functionality and
spans' lifecycles. See the
[`ai.experimental_telemetry` reference](/docs/reference/telemetry) for the
[`ai.telemetry` reference](/docs/reference/telemetry) for the
full API, the span data types, and the durable execution patterns.
2 changes: 1 addition & 1 deletion docs/ai-python/content/docs/basics/testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ model = ai.testing.FakeModel(
]
)

message = await ai.experimental_generate(
message = await ai.generate(
model,
[ai.user_message("Weather in San Francisco as JSON.")],
output_type=Weather,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -545,7 +545,7 @@ See [`ai.errors`](/docs/reference/errors) for the complete error hierarchy.
The Python provider currently supports:

- Language model streaming.
- Buffered language model responses through `ai.experimental_generate`.
- Buffered language model responses through `ai.generate`.
- Structured output.
- Function and provider-executed tools.
- Model listing and connection checks.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ provider-specific namespaces.
- `rerank`: Rerank documents against a query.
- `decide`: Decide typed questions about shared state.

Application code normally uses `ai.stream`, `ai.experimental_generate`, or
Application code normally uses `ai.stream`, `ai.generate`, or
[`ai.ops`](/docs/reference/ops) instead of calling provider methods directly.
A protocol only needs to implement the operations that it supports.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
---
title: "experimental_generate"
title: "generate"
description: Generate a buffered language-model response.
type: reference
summary: Reference for ai.experimental_generate.
summary: Reference for ai.generate.
---

`ai.experimental_generate` makes one language-model call and returns the
`ai.generate` makes one language-model call and returns the
complete assistant `Message` without exposing streamed events.

This API is experimental and may change or be removed.
`ai.experimental_generate` is a deprecated alias for `ai.generate`.

```python
message = await ai.experimental_generate(model, messages)
message = await ai.generate(model, messages)
print(message.text)
```

## Function

```python
await ai.experimental_generate(
await ai.generate(
model,
messages,
*,
Expand All @@ -31,7 +31,7 @@ await ai.experimental_generate(
You can also pass an agent-loop context:

```python
message = await ai.experimental_generate(context=context)
message = await ai.generate(context=context)
```

Pass either `model` and `messages`, or `context=`, not both.
Expand Down Expand Up @@ -63,7 +63,7 @@ class Summary(pydantic.BaseModel):
points: list[str]


message = await ai.experimental_generate(
message = await ai.generate(
model,
[ai.user_message("Summarize the mission as JSON.")],
output_type=Summary,
Expand Down
4 changes: 2 additions & 2 deletions docs/ai-python/content/docs/reference/ai/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ These top-level exports have their own pages under `ai`.

- [`stream`](/docs/reference/ai/stream): Call a model and iterate response
events. The same page documents `Stream`.
- [`experimental_generate`](/docs/reference/ai/experimental-generate): Call a
- [`generate`](/docs/reference/ai/experimental-generate): Call a
model and return a buffered `Message`.
- [`get_model`](/docs/reference/ai/get-model): Resolve a model id into a
`Model`.
Expand All @@ -47,7 +47,7 @@ These module aliases are also re-exported from `ai`.
- [`tools`](/docs/reference/tools): Model-facing tool schema types.
- [`ui`](/docs/reference/ai.ui/ai-sdk): UI adapter namespaces.
- [`util`](/docs/reference/util): Async utility helpers.
- [`experimental_telemetry`](/docs/reference/telemetry): Tracing and
- [`telemetry`](/docs/reference/telemetry): Tracing and
observability APIs.

## Models
Expand Down
6 changes: 5 additions & 1 deletion docs/ai-python/content/docs/reference/ai/stream.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,10 @@ tools use built-in tool events. Generated files arrive as `FileEvent`.

Each yielded event has the current aggregated `event.message`.

`stream.telemetry_span` is the [telemetry span](/docs/reference/telemetry)
for this model call, including replay. It is `None` on streams not created
by `ai.stream`.

## Replay

If the last input message has `replay=True`, `ai.stream` does not call the
Expand All @@ -89,5 +93,5 @@ If the provider stream ends before a finish event, iteration raises
`stream.message`.

Use
[`ai.experimental_generate`](/docs/reference/ai/experimental-generate) when
[`ai.generate`](/docs/reference/ai/experimental-generate) when
you need the complete message without consuming streamed events.
Loading
Loading