Metadata-Version: 2.5
Name: coreweave
Version: 0.1.0b0
Summary: Python SDK for CoreWeave Forge
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api<2,>=1.28.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.28.0
Requires-Dist: opentelemetry-sdk<2,>=1.28.0
Requires-Dist: pydantic<3,>=2.0.0
Requires-Dist: typing-extensions>=4.12.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: google-genai
Requires-Dist: google-genai<=1.23.0,>=1.0.0; extra == 'google-genai'
Provides-Extra: openai
Requires-Dist: openai>=1.99.9; extra == 'openai'
Description-Content-Type: text/markdown

# CoreWeave Forge Python SDK

The Forge Python SDK supports Python 3.10 and newer.

## Python agent tracing

The `coreweave.forge.agentlens.tracing` subpackage sends agent, LLM, tool, and sub-agent
spans to the Weave Agents experience over OTLP/HTTP. It does not depend on the
full `weave` or `wandb` Python packages.

```python
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")  # Reads WANDB_API_KEY.

with tracing.Conversation(agent_name="research-agent") as conversation:
    with conversation.start_turn(user_message="Find the answer") as turn:
        with turn.start_llm(model="gpt-5") as llm:
            llm.output("The answer is 42.")

tracing.shutdown()
```

### OpenAI integration

Install the optional provider dependency, then initialize tracing before making
OpenAI calls:

```bash
pip install "coreweave[openai]"
```

```python
from openai import OpenAI
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")
client = OpenAI()

response = client.responses.create(
    model="gpt-5-mini",
    input="Hello",
)

tracing.shutdown()
```

`tracing.init()` patches an OpenAI SDK imported before initialization and
installs an import hook for one imported later. Set
`autopatch_integrations=False` to opt out, or use
`tracing.integrations.patch_openai()` and
`tracing.integrations.unpatch_openai()` for explicit control. Sync and async
Chat Completions, structured-output parsing, Responses, streaming, and image
generation retain their native SDK interfaces while AgentLens captures
completed output and usage.

The integration records multimodal messages, tool calls, request settings,
cached and reasoning tokens, response metadata, and integration provenance.
Standalone calls get a synthetic `openai SDK` turn. The integration supports
`openai>=1.99.9`.

### Anthropic integration

Install the optional provider dependency and initialize tracing normally:

```bash
pip install "coreweave[anthropic]"
```

```python
from anthropic import Anthropic
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")
client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
)

tracing.shutdown()
```

`tracing.init()` patches an Anthropic SDK that was imported earlier and installs
an import hook for one imported later. Set `autopatch_integrations=False` to opt
out, or use
`tracing.integrations.patch_anthropic()` and
`tracing.integrations.unpatch_anthropic()` for explicit control. Sync and async
Messages calls, `stream=True`, the Messages stream helper, structured output
parsing, tool
calls, media, request settings, token usage, and prompt-cache usage are traced.

Calls made inside an active AgentLens turn become children of that turn. A
standalone provider call gets a synthetic `anthropic SDK` turn so it remains
visible in AgentLens. The integration supports `anthropic>=0.18.0`.

### Google Gen AI integration

Install the optional Gemini provider dependency and initialize tracing before
creating or using a Google Gen AI client:

```bash
pip install "coreweave[google-genai]"
```

```python
from google import genai
from coreweave.forge.agentlens import tracing

tracing.init("entity/project")
client = genai.Client()

response = client.models.generate_content(
    model="gemini-flash-latest",
    contents="Hello",
)

tracing.shutdown()
```

`tracing.init()` patches an imported `google.genai` SDK and watches for one
imported later. Set `autopatch_integrations=False` to opt out, or use
`tracing.integrations.patch_google_genai()` and
`tracing.integrations.unpatch_google_genai()` explicitly. Sync and async
content generation, streaming, chat helpers, and Imagen generation retain
their native interfaces while AgentLens records messages, system instructions,
tools, media, request settings, response metadata, token usage, cached input,
and thinking tokens.

Standalone calls get a synthetic `gemini SDK` (or `vertex_ai SDK`) turn. The
integration supports `google-genai>=1.0.0,<=1.23.0`.

Recorded request settings include temperature, top-k, top-p, frequency and
presence penalties, token limits, stop sequences, seed, and candidate count.
Imagen's requested image count is recorded as the choice count. Token usage
includes Google's reported total when available, including an explicit zero;
an omitted total stays omitted.

The `start_*` factories start spans immediately. You can pair them with
`end()` or the matching `end_*` function instead of using `with`; entering a
factory-created span as a context manager does not start it twice. Direct
`Turn`, `LLM`, `Tool`, and `SubAgent` construction remains non-emitting until
`start()` or context-manager entry, so these models can also represent batch data.

`project_name` must include the entity because the tracing package does not
call W&B account APIs to discover one. `init` accepts explicit `api_key` and
`base_url` arguments. Otherwise it reads `WANDB_API_KEY`,
`WF_TRACE_SERVER_URL`, and `WANDB_BASE_URL`, with `.netrc` as the API-key
fallback.

Call `tracing.force_flush()` before a latency-sensitive process exit.
`tracing.shutdown()` flushes and closes the export worker and is also
registered with `atexit`. Calling `tracing.init` again reroutes new spans to
the new project. The immediately previous session stays open until the next
`init` or `shutdown`; finish its spans before then to avoid losing them. New
children started after reinitialization use the new project even when their
parent belongs to the previous one.

The package owns a private `TracerProvider`. It exports spans created through
this package and does not replace the application's global OpenTelemetry
provider or export spans created by unrelated instrumentation.

### SDK attribution

Every exported span's OTLP resource includes `wandb.sdk.name = "forge"` to
identify Forge SDK traffic separately from regular Weave SDK traffic.
`wandb.sdk.version` records the package version, and `wandb.sdk.language` is
`"python"`. These attributes are independent of the configurable `service.name`.

### Smoke test

The smoke script emits one synthetic agent turn and LLM span. It does not call
an LLM provider.

```bash
WANDB_API_KEY=<key> \
FORGE_TRACE_PROJECT=<entity/project> \
uv run python examples/tracing_smoke_test.py
```

The command exits only after the exporter flushes and prints the conversation
ID to find in the Weave Agents experience.

### Media

OTLP GenAI message attributes support media parts:

- Raw bytes become a base64 `blob` part.
- A base64 string can be supplied as blob content.
- HTTP, data, and other URIs become `uri` parts.
- Provider-side file identifiers become `file` parts.

```python
with turn.start_llm(model="vision-model") as llm:
    llm.attach_media(uri="https://example.test/image.png", modality="image")
```

Media is included in the JSON value of `gen_ai.input.messages`. The tracing
subpackage does not upload media into the Weave object store. Prefer URIs for
large media because inline blobs count toward the OTLP request-size limit.

### Content privacy

Set `include_content=False` on `Conversation` to omit messages, tool arguments,
tool results, reasoning, and media. Spans retain their owning conversation
when completed from another thread or context. The tracing subpackage does
not perform PII detection or redaction.

## Development

Run these commands from `python/`:

```bash
uv sync --locked --group test
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build
```

## License

Copyright 2026 CoreWeave, Inc.

Licensed under the [Apache License, Version 2.0](LICENSE).
