weave.trace.weave_client

API Overview

Classes

weave_client.WeaveClient
weave_client.Call: A Call represents a single operation that was executed as part of a trace.

Functions

weave_client.PaginatedIterator

`class` `WeaveClient`

`method` `init`

__init__(
    entity: 'str',
    project: 'str',
    server: 'TraceServerInterface',
    ensure_project_exists: 'bool' = True
)

`property` num_outstanding_jobs

Returns the total number of pending jobs across all executors and the server.

This property can be used to check the progress of background tasks without blocking the main thread.

Returns:

int: The total number of pending jobs

`method` `add_cost`

add_cost(
    llm_id: 'str',
    prompt_token_cost: 'float',
    completion_token_cost: 'float',
    effective_date: 'datetime | None' = datetime.datetime(2025, 4, 30, 23, 50, 40, 886784, tzinfo=datetime.timezone.utc),
    prompt_token_cost_unit: 'str | None' = 'USD',
    completion_token_cost_unit: 'str | None' = 'USD',
    provider_id: 'str | None' = 'default'
) → CostCreateRes

Add a cost to the current project.

Examples:

     client.add_cost(llm_id="my_expensive_custom_model", prompt_token_cost=1, completion_token_cost=2)
     client.add_cost(llm_id="my_expensive_custom_model", prompt_token_cost=500, completion_token_cost=1000, effective_date=datetime(1998, 10, 3))

Args:

llm_id: The ID of the LLM. eg "gpt-4o-mini-2024-07-18"
prompt_token_cost: The cost per prompt token. eg .0005
completion_token_cost: The cost per completion token. eg .0015
effective_date: Defaults to the current date. A datetime.datetime object.
provider_id: The provider of the LLM. Defaults to "default". eg "openai"
prompt_token_cost_unit: The unit of the cost for the prompt tokens. Defaults to "USD". (Currently unused, will be used in the future to specify the currency type for the cost eg "tokens" or "time")
completion_token_cost_unit: The unit of the cost for the completion tokens. Defaults to "USD". (Currently unused, will be used in the future to specify the currency type for the cost eg "tokens" or "time")

Returns: A CostCreateRes object. Which has one field called a list of tuples called ids. Each tuple contains the llm_id and the id of the created cost object.

`method` `call`

call(call_id: 'str', include_costs: 'bool' = False) → WeaveObject

`method` `calls`

calls(
    filter: 'CallsFilter | None' = None,
    include_costs: 'bool' = False
) → CallsIter

`method` `create_call`

create_call(
    op: 'str | Op',
    inputs: 'dict',
    parent: 'Call | None' = None,
    attributes: 'dict | None' = None,
    display_name: 'str | Callable[[Call], str] | None' = None,
    use_stack: 'bool' = True
) → Call

Create, log, and push a call onto the runtime stack.

Args:

op: The operation producing the call, or the name of an anonymous operation.
inputs: The inputs to the operation.
parent: The parent call. If parent is not provided, the current run is used as the parent.
display_name: The display name for the call. Defaults to None.
attributes: The attributes for the call. Defaults to None.
use_stack: Whether to push the call onto the runtime stack. Defaults to True.

Returns: The created Call object.

`method` `delete_call`

delete_call(call: 'Call') → None

`method` `delete_calls`

delete_calls(call_ids: 'list[str]') → None

Delete calls by their IDs.

Deleting a call will also delete all of its children.

Args:

call_ids: A list of call IDs to delete. Ex: ["2F0193e107-8fcf-7630-b576-977cc3062e2e"]

`method` `delete_object_version`

delete_object_version(object: 'ObjectRef') → None

`method` `delete_op_version`

delete_op_version(op: 'OpRef') → None

`method` `fail_call`

fail_call(call: 'Call', exception: 'BaseException') → None

Fail a call with an exception. This is a convenience method for finish_call.

`method` `feedback`

feedback(
    query: 'Query | str | None' = None,
    reaction: 'str | None' = None,
    offset: 'int' = 0,
    limit: 'int' = 100
) → FeedbackQuery

`method` `finish`

finish(
    use_progress_bar: 'bool' = True,
    callback: 'Callable[[FlushStatus], None] | None' = None
) → None

Flushes all background tasks to ensure they are processed.

This method blocks until all currently enqueued jobs are processed, displaying a progress bar to show the status of the pending tasks. It ensures parallel processing during main thread execution and can improve performance when user code completes before data has been uploaded to the server.

Args:

use_progress_bar: Whether to display a progress bar during flush. Set to False for environments where a progress bar would not render well (e.g., CI environments).
callback: Optional callback function that receives status updates. Overrides use_progress_bar.

`method` `finish_call`

finish_call(
    call: 'Call',
    output: 'Any' = None,
    exception: 'BaseException | None' = None,
    op: 'Op | None' = None
) → None

`method` `flush`

flush() → None

Flushes background asynchronous tasks, safe to call multiple times.

`method` `get`

get(ref: 'ObjectRef', objectify: 'bool' = True) → Any

`method` `get_call`

get_call(
    call_id: 'str',
    include_costs: 'bool' = False,
    include_feedback: 'bool' = False,
    columns: 'list[str] | None' = None
) → WeaveObject

Get a single call by its ID.

Args:

call_id: The ID of the call to get.
include_costs: If true, cost info is included at summary.weave
include_feedback: If true, feedback info is included at summary.weave.feedback
columns: A list of columns to include in the response. If None, all columns are included. Specifying fewer columns may be more performant.
Some columns are always included: id, project_id, trace_id, op_name, started_at

Returns: A call object.

`method` `get_calls`

get_calls(
    filter: 'CallsFilter | None' = None,
    limit: 'int | None' = None,
    offset: 'int | None' = None,
    sort_by: 'list[SortBy] | None' = None,
    query: 'Query | None' = None,
    include_costs: 'bool' = False,
    include_feedback: 'bool' = False,
    columns: 'list[str] | None' = None,
    scored_by: 'str | list[str] | None' = None,
    page_size: 'int' = 1000
) → CallsIter

Get a list of calls.

Args:

filter: A filter to apply to the calls.
limit: The maximum number of calls to return.
offset: The number of calls to skip.
sort_by: A list of fields to sort the calls by.
query: A mongo-like query to filter the calls.
include_costs: If true, cost info is included at summary.weave
include_feedback: If true, feedback info is included at summary.weave.feedback
columns: A list of columns to include in the response. If None, all columns are included. Specifying fewer columns may be more performant.
Some columns are always included: id, project_id, trace_id, op_name, started_at
scored_by: Accepts a list or single item. Each item is a name or ref uri of a scorer to filter by. Multiple scorers are ANDed together. If passing in just the name, then scores for all versions of the scorer are returned. If passing in the full ref URI, then scores for a specific version of the scorer are returned.
page_size: Tune performance by changing the number of calls fetched at a time.

Returns: An iterator of calls.

`method` `get_feedback`

get_feedback(
    query: 'Query | str | None' = None,
    reaction: 'str | None' = None,
    offset: 'int' = 0,
    limit: 'int' = 100
) → FeedbackQuery

Query project for feedback.

Examples:

    # Fetch a specific feedback object.
    # Note that this still returns a collection, which is expected
    # to contain zero or one item(s).
    client.get_feedback("1B4082A3-4EDA-4BEB-BFEB-2D16ED59AA07")

    # Find all feedback objects with a specific reaction.
    client.get_feedback(reaction="👍", limit=10)

Args:

query: A mongo-style query expression. For convenience, also accepts a feedback UUID string.
reaction: For convenience, filter by a particular reaction emoji.
offset: The offset to start fetching feedback objects from.
limit: The maximum number of feedback objects to fetch.

Returns: A FeedbackQuery object.

`method` `purge_costs`

purge_costs(ids: 'list[str] | str') → None

Purge costs from the current project.

Examples:

     client.purge_costs([ids])
     client.purge_costs(ids)

Args:

ids: The cost IDs to purge. Can be a single ID or a list of IDs.

`method` `query_costs`

query_costs(
    query: 'Query | str | None' = None,
    llm_ids: 'list[str] | None' = None,
    offset: 'int' = 0,
    limit: 'int' = 100
) → list[CostQueryOutput]

Query project for costs.

Examples:

     # Fetch a specific cost object.
     # Note that this still returns a collection, which is expected
     # to contain zero or one item(s).
     client.query_costs("1B4082A3-4EDA-4BEB-BFEB-2D16ED59AA07")

     # Find all cost objects with a specific reaction.
     client.query_costs(llm_ids=["gpt-4o-mini-2024-07-18"], limit=10)

Args:

query: A mongo-style query expression. For convenience, also accepts a cost UUID string.
llm_ids: For convenience, filter for a set of llm_ids.
offset: The offset to start fetching cost objects from.
limit: The maximum number of cost objects to fetch.

Returns: A CostQuery object.

`method` `save`

save(val: 'Any', name: 'str', branch: 'str' = 'latest') → Any

Do not call directly, use weave.publish() instead.

Args:

val: The object to save.
name: The name to save the object under.
branch: The branch to save the object under. Defaults to "latest".

Returns: A deserialized version of the saved object.

`class` `Call`

A Call represents a single operation that was executed as part of a trace.

`method` `init`

__init__(
    _op_name: 'str | Future[str]',
    trace_id: 'str',
    project_id: 'str',
    parent_id: 'str | None',
    inputs: 'dict',
    id: 'str | None' = None,
    output: 'Any' = None,
    exception: 'str | None' = None,
    summary: 'dict | None' = None,
    _display_name: 'str | Callable[[Call], str] | None' = None,
    attributes: 'dict | None' = None,
    started_at: 'datetime | None' = None,
    ended_at: 'datetime | None' = None,
    deleted_at: 'datetime | None' = None,
    _children: 'list[Call]' = &lt;factory&gt;,
    _feedback: 'RefFeedbackQuery | None' = None
) → None

`property` display_name

`property` feedback

`property` func_name

The decorated function's name that produced this call.

This is different from op_name which is usually the ref of the op.

`property` op_name

`property` ref

`property` ui_url

`method` `apply_scorer`

apply_scorer(
    scorer: 'Op | Scorer',
    additional_scorer_kwargs: 'dict | None' = None
) → ApplyScorerResult

apply_scorer is a method that applies a Scorer to a Call. This is useful for guarding application logic with a scorer and/or monitoring the quality of critical ops. Scorers are automatically logged to Weave as Feedback and can be used in queries & analysis.

Args:

scorer: The Scorer to apply.
additional_scorer_kwargs: Additional kwargs to pass to the scorer. This is useful for passing in additional context that is not part of the call inputs.useful for passing in additional context that is not part of the call inputs.

Returns: The result of the scorer application in the form of an ApplyScorerResult.

class ApplyScorerSuccess:

 - <b>`    result`</b>:  Any

 - <b>`    score_call`</b>:  Call

Example usage:

my_scorer = ... # construct a scorer
prediction, prediction_call = my_op.call(input_data)
result, score_call = prediction.apply_scorer(my_scorer)

`method` `children`

children(page_size: 'int' = 1000) → CallsIter

Get the children of the call.

Args:

page_size: Tune performance by changing the number of calls fetched at a time.

Returns: An iterator of calls.

`method` `delete`

delete() → bool

Delete the call.

`method` `remove_display_name`

remove_display_name() → None

`method` `set_display_name`

set_display_name(name: 'str | None') → None

Set the display name for the call.

Args:

name: The display name to set for the call.

Example:

result, call = my_function.call("World")
call.set_display_name("My Custom Display Name")

`method` `to_dict`

to_dict() → CallDict

`function` `PaginatedIterator`

PaginatedIterator(*args, **kwargs)

weave.trace.weave_client

API Overview

Classes​

Functions​

class WeaveClient​

method __init__​

property num_outstanding_jobs​

method add_cost​

method call​

method calls​

method create_call​

method delete_call​

method delete_calls​

method delete_object_version​

method delete_op_version​

method fail_call​

method feedback​

method finish​

method finish_call​

method flush​

method get​

method get_call​

method get_calls​

method get_feedback​

method purge_costs​

method query_costs​

method save​

class Call​

method __init__​

property display_name​

property feedback​

property func_name​

property op_name​

property ref​

property ui_url​

method apply_scorer​

method children​

method delete​

method remove_display_name​

method set_display_name​

method to_dict​

function PaginatedIterator​

Classes

Functions

`class` `WeaveClient`

`method` `init`

`property` num_outstanding_jobs

`method` `add_cost`

`method` `call`

`method` `calls`

`method` `create_call`

`method` `delete_call`

`method` `delete_calls`

`method` `delete_object_version`

`method` `delete_op_version`

`method` `fail_call`

`method` `feedback`

`method` `finish`

`method` `finish_call`

`method` `flush`

`method` `get`

`method` `get_call`

`method` `get_calls`

`method` `get_feedback`

`method` `purge_costs`

`method` `query_costs`

`method` `save`

`class` `Call`

`method` `init`

`property` display_name

`property` feedback

`property` func_name

`property` op_name

`property` ref

`property` ui_url

`method` `apply_scorer`

`method` `children`

`method` `delete`

`method` `remove_display_name`

`method` `set_display_name`

`method` `to_dict`

`function` `PaginatedIterator`