From 4f7df0a2df3d448e8e52dce702333e051d728403 Mon Sep 17 00:00:00 2001 From: Tim Sweeney Date: Fri, 9 Aug 2024 14:41:51 -0700 Subject: [PATCH] chore: Python Docs: Link to source, better pydantic objects (#2102) * init * init * init * docgen --- docs/docs/reference/python-sdk/weave/index.md | 248 +-- .../weave/trace/weave.trace.util.md | 14 + .../weave.trace_server.interface.query.md | 256 +-- ...e.trace_server.remote_http_trace_server.md | 129 +- ...ave.trace_server.trace_server_interface.md | 1629 ++++++++++------- .../python-sdk/weave/weave.feedback.md | 34 + .../python-sdk/weave/weave.weave_client.md | 48 +- docs/scripts/generate_python_sdk_docs.py | 167 +- 8 files changed, 1566 insertions(+), 959 deletions(-) diff --git a/docs/docs/reference/python-sdk/weave/index.md b/docs/docs/reference/python-sdk/weave/index.md index 1a2337ee634..465b4cc22d4 100644 --- a/docs/docs/reference/python-sdk/weave/index.md +++ b/docs/docs/reference/python-sdk/weave/index.md @@ -35,6 +35,8 @@ The top-level functions and classes for working with Weave. --- + + ### function `init` ```python @@ -63,6 +65,8 @@ Following init, calls of weave.op() decorated functions will be logged to the sp --- + + ### function `publish` ```python @@ -89,6 +93,8 @@ TODO: Need to document how name works with this change. --- + + ### function `ref` ```python @@ -114,6 +120,8 @@ TODO: what happens if obj does not exist --- + + ### function `get_current_call` ```python @@ -159,6 +167,8 @@ print(mycall.id) --- + + ### function `finish` ```python @@ -171,6 +181,8 @@ Following finish, calls of weave.op() decorated functions will no longer be logg --- + + ### function `op` ```python @@ -204,81 +216,56 @@ await extract() # calls the function and tracks the call in the Weave UI ``` --- + + + ## class `Object` - + + + + + +**Pydantic Fields:** + +- `name`: `typing.Optional[str]` +- `description`: `typing.Optional[str]` +--- + + + +### classmethod `handle_relocatable_object` + ```python -class Object(BaseModel): - name: Optional[str] = None - description: Optional[str] = None - - # Allow Op attributes - model_config = ConfigDict( - ignored_types=(Op,), - arbitrary_types_allowed=True, - protected_namespaces=(), - extra="forbid", - ) - - __str__ = BaseModel.__repr__ - - # This is a "wrap" validator meaning we can run our own logic before - # and after the standard pydantic validation. - @model_validator(mode="wrap") - @classmethod - def handle_relocatable_object( - cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo - ) -> Any: - if isinstance(v, ObjectRef): - return v.get() - if isinstance(v, WeaveObject): - # This is a relocated object, so destructure it into a dictionary - # so pydantic can validate it. - keys = v._val.__dict__.keys() - fields = {} - for k in keys: - if k.startswith("_"): - continue - val = getattr(v, k) - fields[k] = val - - # pydantic validation will construct a new pydantic object - def is_ignored_type(v: type) -> bool: - return isinstance(v, cls.model_config["ignored_types"]) - - allowed_fields = {k: v for k, v in fields.items() if not is_ignored_type(v)} - new_obj = handler(allowed_fields) - for k, kv in fields.items(): - if is_ignored_type(kv): - new_obj.__dict__[k] = kv - - # transfer ref to new object - # We can't attach a ref directly to pydantic objects yet. - # TODO: fix this. I think dedupe may make it so the user data ends up - # working fine, but not setting a ref here will cause the client - # to do extra work. - if isinstance(v, WeaveObject): - ref = get_ref(v) - new_obj.__dict__["ref"] = ref - # return new_obj - - return new_obj - return handler(v) - - def model_post_init(self, __context: Any) -> None: - super().model_post_init(__context) - - # This binds the call "method" to the Op instance - # - before: obj.method.call(obj, ...) - # - after: obj.method.call(...) - for k in dir(self): - if not k.startswith("__") and isinstance(getattr(self, k), Op): - op = getattr(self, k) - op.__dict__["call"] = partial(call, op, self) +handle_relocatable_object( + v: Any, + handler: ValidatorFunctionWrapHandler, + info: ValidationInfo +) → Any +``` + + + + + +--- + + + +### method `model_post_init` +```python +model_post_init(_Object__context: Any) → None ``` - + + + + + + --- + + ## class `Dataset` Dataset object with easy saving and automatic versioning @@ -306,31 +293,14 @@ example_label = dataset_ref.rows[2]['sentence'] ``` ---- - -#### property model_extra - -Get extra fields set during validation. - - - -**Returns:** - A dictionary of extra fields, or `None` if `config.extra` is not set to `"allow"`. +**Pydantic Fields:** +- `name`: `typing.Optional[str]` +- `description`: `typing.Optional[str]` +- `rows`: `` --- -#### property model_fields_set - -Returns the set of fields that have been explicitly set on this model instance. - - - -**Returns:** - A set of strings representing the fields that have been set, i.e. that were not filled from defaults. - - - ---- + ### classmethod `convert_to_table` @@ -345,6 +315,8 @@ convert_to_table(rows: Any) → Table --- + + ## class `Model` Intended to capture a combination of code and data the operates on an input. For example it might call an LLM with a prompt to make a prediction or generate text. @@ -368,31 +340,13 @@ class YourModel(Model): ``` ---- - -#### property model_extra - -Get extra fields set during validation. - - - -**Returns:** - A dictionary of extra fields, or `None` if `config.extra` is not set to `"allow"`. +**Pydantic Fields:** +- `name`: `typing.Optional[str]` +- `description`: `typing.Optional[str]` --- -#### property model_fields_set - -Returns the set of fields that have been explicitly set on this model instance. - - - -**Returns:** - A set of strings representing the fields that have been set, i.e. that were not filled from defaults. - - - ---- + ### method `get_infer_method` @@ -407,6 +361,8 @@ get_infer_method() → Callable --- + + ## class `Evaluation` Sets up an evaluation which includes a set of scorers and a dataset. @@ -452,31 +408,17 @@ asyncio.run(evaluation.evaluate(function_to_evaluate)) ``` ---- - -#### property model_extra - -Get extra fields set during validation. - - - -**Returns:** - A dictionary of extra fields, or `None` if `config.extra` is not set to `"allow"`. +**Pydantic Fields:** +- `name`: `typing.Optional[str]` +- `description`: `typing.Optional[str]` +- `dataset`: `typing.Union[flow.dataset.Dataset, list]` +- `scorers`: `typing.Optional[list[typing.Union[typing.Callable, trace.op.Op, flow.scorer.Scorer]]]` +- `preprocess_model_input`: `typing.Optional[typing.Callable]` +- `trials`: `` --- -#### property model_fields_set - -Returns the set of fields that have been explicitly set on this model instance. - - - -**Returns:** - A set of strings representing the fields that have been set, i.e. that were not filled from defaults. - - - ---- + ### method `evaluate` @@ -490,6 +432,8 @@ evaluate(model: Union[Callable, Model]) → dict --- + + ### method `model_post_init` ```python @@ -502,6 +446,8 @@ model_post_init(_Evaluation__context: Any) → None --- + + ### method `predict_and_score` ```python @@ -514,6 +460,8 @@ predict_and_score(model: Union[Callable, Model], example: dict) → dict --- + + ### method `summarize` ```python @@ -527,37 +475,21 @@ summarize(eval_table: EvaluationResults) → dict --- -## class `Scorer` - - - - + ---- +## class `Scorer` -#### property model_extra -Get extra fields set during validation. -**Returns:** - A dictionary of extra fields, or `None` if `config.extra` is not set to `"allow"`. +**Pydantic Fields:** +- `name`: `typing.Optional[str]` +- `description`: `typing.Optional[str]` --- -#### property model_fields_set - -Returns the set of fields that have been explicitly set on this model instance. - - - -**Returns:** - A set of strings representing the fields that have been set, i.e. that were not filled from defaults. - - - ---- + ### method `score` @@ -571,6 +503,8 @@ score(target: Any, model_output: Any) → Any --- + + ### method `summarize` ```python diff --git a/docs/docs/reference/python-sdk/weave/trace/weave.trace.util.md b/docs/docs/reference/python-sdk/weave/trace/weave.trace.util.md index 6512c9843fc..441a6e26645 100644 --- a/docs/docs/reference/python-sdk/weave/trace/weave.trace.util.md +++ b/docs/docs/reference/python-sdk/weave/trace/weave.trace.util.md @@ -25,6 +25,8 @@ sidebar_label: util --- + + ## class `ContextAwareThreadPoolExecutor` A ThreadPoolExecutor that runs functions with the context of the caller. @@ -42,6 +44,8 @@ with concurrent.futures.ThreadPoolExecutor() as executor: executor.map(_wrapped_fn, vals) ``` + + ### method `__init__` ```python @@ -57,6 +61,8 @@ __init__(*args: Any, **kwargs: Any) → None --- + + ### method `map` ```python @@ -74,6 +80,8 @@ map( --- + + ### method `submit` ```python @@ -87,6 +95,8 @@ submit(fn: Callable, *args: Any, **kwargs: Any) → Any --- + + ## class `ContextAwareThread` A Thread that runs functions with the context of the caller. @@ -105,6 +115,8 @@ thread = threading.Thread(target=run_with_context(your_func, *args, **kwargs)) thread.start() ``` + + ### method `__init__` ```python @@ -154,6 +166,8 @@ This is a non-negative integer. See the get_native_id() function. This represent --- + + ### method `run` ```python diff --git a/docs/docs/reference/python-sdk/weave/trace_server/interface/weave.trace_server.interface.query.md b/docs/docs/reference/python-sdk/weave/trace_server/interface/weave.trace_server.interface.query.md index 8c2697ac46c..65a6509d0bc 100644 --- a/docs/docs/reference/python-sdk/weave/trace_server/interface/weave.trace_server.interface.query.md +++ b/docs/docs/reference/python-sdk/weave/trace_server/interface/weave.trace_server.interface.query.md @@ -57,146 +57,186 @@ simplifications: --- + + + ## class `AndOperation` - -```python -class AndOperation(BaseModel): - and_: typing.List["Operand"] = Field(alias="$and") -``` - + + + + +**Pydantic Fields:** + +- `$and`: `typing.List[typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]]` + --- + + + ## class `ContainsOperation` - -```python -class ContainsOperation(BaseModel): - contains_: "ContainsSpec" = Field(alias="$contains") -``` - + + + + +**Pydantic Fields:** + +- `$contains`: `` + --- + + + ## class `ContainsSpec` - -```python -class ContainsSpec(BaseModel): - input: "Operand" - substr: "Operand" - case_insensitive: typing.Optional[bool] = False -``` - + + + + +**Pydantic Fields:** + +- `input`: `typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]` +- `substr`: `typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]` +- `case_insensitive`: `typing.Optional[bool]` + --- + + + ## class `ConvertOperation` - -```python -class ConvertOperation(BaseModel): - convert_: "ConvertSpec" = Field(alias="$convert") -``` - + + + + +**Pydantic Fields:** + +- `$convert`: `` + --- + + + ## class `ConvertSpec` - -```python -class ConvertSpec(BaseModel): - input: "Operand" - # Subset of https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-bson-types - to: CastTo -``` - + + + + +**Pydantic Fields:** + +- `input`: `typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]` +- `to`: `typing.Literal['double', 'string', 'int', 'bool', 'exists']` + --- + + + ## class `EqOperation` - -```python -class EqOperation(BaseModel): - eq_: typing.Tuple["Operand", "Operand"] = Field(alias="$eq") -``` - + + + + +**Pydantic Fields:** + +- `$eq`: `typing.Tuple[typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation], typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]]` + --- + + + ## class `GetFieldOperator` - -```python -class GetFieldOperator(BaseModel): - # Tim: We will likely want to revisit this before making it public. Here are some concerns: - # 1. Mongo explicitly says that `getField` is used to access fields without dot notation - this - # is not how we are handling it here - we are using dot notation - this could be resolved by - # supporting the `$field.with.path` shorthand. - # 2. As Jamie pointed out, the parsing of this field is not very robust and susceptible to issues when: - # - The field part name contains a dot - # - The field part name is a valid integer (currently interpreted as a list index) - # - The field part name contains a double quote (will result in failed lookup - see `_quote_json_path` in `clickhouse_trace_server_batched.py`) - # These issues could be resolved by using an alternative syntax (perhaps backticks, square brackets, etc.). However - # this would diverge from the current Mongo syntax. - get_field_: str = Field(alias="$getField") - -``` - + + + + + +**Pydantic Fields:** + +- `$getField`: `` + --- + + + ## class `GtOperation` - -```python -class GtOperation(BaseModel): - gt_: typing.Tuple["Operand", "Operand"] = Field(alias="$gt") -``` - + + + + +**Pydantic Fields:** + +- `$gt`: `typing.Tuple[typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation], typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]]` + --- + + + ## class `GteOperation` - -```python -class GteOperation(BaseModel): - gte_: typing.Tuple["Operand", "Operand"] = Field(alias="$gte") -``` - + + + + +**Pydantic Fields:** + +- `$gte`: `typing.Tuple[typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation], typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]]` + --- + + + ## class `LiteralOperation` - -```python -class LiteralOperation(BaseModel): - literal_: typing.Union[ - str, - int, - float, - bool, - dict[str, "LiteralOperation"], - list["LiteralOperation"], - None, - ] = Field(alias="$literal") - -``` - + + + + + +**Pydantic Fields:** + +- `$literal`: `typing.Union[str, int, float, bool, dict[str, 'LiteralOperation'], list['LiteralOperation'], NoneType]` + --- + + + ## class `NotOperation` - -```python -class NotOperation(BaseModel): - not_: typing.Tuple["Operand"] = Field(alias="$not") -``` - + + + + +**Pydantic Fields:** + +- `$not`: `typing.Tuple[typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]]` + --- + + + ## class `OrOperation` - -```python -class OrOperation(BaseModel): - or_: typing.List["Operand"] = Field(alias="$or") -``` - + + + + +**Pydantic Fields:** + +- `$or`: `typing.List[typing.Union[LiteralOperation, GetFieldOperator, ConvertOperation, AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]]` + --- + + + ## class `Query` - -```python -class Query(BaseModel): - # Here, we use `expr_` to match the MongoDB query language's "aggregation" operator syntax. - # This is certainly a subset of the full MongoDB query language, but it is a good starting point. - # https://www.mongodb.com/docs/manual/reference/operator/query/expr/#mongodb-query-op.-expr - expr_: "Operation" = Field(alias="$expr") - # In the future, we could have other top-level Query Operators as described here: - # https://www.mongodb.com/docs/manual/reference/operator/query/ - -``` - \ No newline at end of file + + + + + +**Pydantic Fields:** + +- `$expr`: `typing.Union[AndOperation, OrOperation, NotOperation, EqOperation, GtOperation, GteOperation, ContainsOperation]` diff --git a/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.remote_http_trace_server.md b/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.remote_http_trace_server.md index 91bdce54f33..4e1f79373e3 100644 --- a/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.remote_http_trace_server.md +++ b/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.remote_http_trace_server.md @@ -28,11 +28,15 @@ sidebar_label: remote_http_trace_server --- + + ## class `RemoteHTTPTraceServer` + + ### method `__init__` ```python @@ -52,6 +56,8 @@ __init__( --- + + ### method `call_end` ```python @@ -64,6 +70,8 @@ call_end(req: Union[CallEndReq, Dict[str, Any]]) → CallEndRes --- + + ### method `call_read` ```python @@ -76,6 +84,8 @@ call_read(req: Union[CallReadReq, Dict[str, Any]]) → CallReadRes --- + + ### method `call_start` ```python @@ -88,6 +98,8 @@ call_start(req: Union[CallStartReq, Dict[str, Any]]) → CallStartRes --- + + ### method `call_update` ```python @@ -100,6 +112,8 @@ call_update(req: Union[CallUpdateReq, Dict[str, Any]]) → CallUpdateRes --- + + ### method `calls_delete` ```python @@ -112,6 +126,8 @@ calls_delete(req: Union[CallsDeleteReq, Dict[str, Any]]) → CallsDeleteRes --- + + ### method `calls_query` ```python @@ -124,6 +140,8 @@ calls_query(req: Union[CallsQueryReq, Dict[str, Any]]) → CallsQueryRes --- + + ### method `calls_query_stats` ```python @@ -138,6 +156,8 @@ calls_query_stats( --- + + ### method `calls_query_stream` ```python @@ -150,6 +170,8 @@ calls_query_stream(req: CallsQueryReq) → Iterator[CallSchema] --- + + ### method `ensure_project_exists` ```python @@ -162,6 +184,8 @@ ensure_project_exists(entity: str, project: str) → None --- + + ### method `feedback_create` ```python @@ -176,6 +200,8 @@ feedback_create( --- + + ### method `feedback_purge` ```python @@ -188,6 +214,8 @@ feedback_purge(req: Union[FeedbackPurgeReq, Dict[str, Any]]) → FeedbackPurgeRe --- + + ### method `feedback_query` ```python @@ -200,6 +228,8 @@ feedback_query(req: Union[FeedbackQueryReq, Dict[str, Any]]) → FeedbackQueryRe --- + + ### method `file_content_read` ```python @@ -212,6 +242,8 @@ file_content_read(req: FileContentReadReq) → FileContentReadRes --- + + ### method `file_create` ```python @@ -224,6 +256,8 @@ file_create(req: FileCreateReq) → FileCreateRes --- + + ### classmethod `from_env` ```python @@ -236,6 +270,8 @@ from_env(should_batch: bool = False) → RemoteHTTPTraceServer --- + + ### method `obj_create` ```python @@ -248,6 +284,8 @@ obj_create(req: Union[ObjCreateReq, Dict[str, Any]]) → ObjCreateRes --- + + ### method `obj_read` ```python @@ -260,6 +298,8 @@ obj_read(req: Union[ObjReadReq, Dict[str, Any]]) → ObjReadRes --- + + ### method `objs_query` ```python @@ -272,6 +312,8 @@ objs_query(req: Union[ObjQueryReq, Dict[str, Any]]) → ObjQueryRes --- + + ### method `op_create` ```python @@ -284,6 +326,8 @@ op_create(req: Union[OpCreateReq, Dict[str, Any]]) → OpCreateRes --- + + ### method `op_read` ```python @@ -296,6 +340,8 @@ op_read(req: Union[OpReadReq, Dict[str, Any]]) → OpReadRes --- + + ### method `ops_query` ```python @@ -308,6 +354,8 @@ ops_query(req: Union[OpQueryReq, Dict[str, Any]]) → OpQueryRes --- + + ### method `refs_read_batch` ```python @@ -320,6 +368,8 @@ refs_read_batch(req: Union[RefsReadBatchReq, Dict[str, Any]]) → RefsReadBatchR --- + + ### method `server_info` ```python @@ -332,6 +382,8 @@ server_info() → ServerInfoRes --- + + ### method `set_auth` ```python @@ -344,6 +396,8 @@ set_auth(auth: Tuple[str, str]) → None --- + + ### method `table_create` ```python @@ -354,6 +408,8 @@ Similar to `calls/batch_upsert`, we can dynamically adjust the payload size due --- + + ### method `table_query` ```python @@ -366,6 +422,8 @@ table_query(req: Union[TableQueryReq, Dict[str, Any]]) → TableQueryRes --- + + ### method `table_update` ```python @@ -376,40 +434,59 @@ Similar to `calls/batch_upsert`, we can dynamically adjust the payload size due --- + + + ## class `ServerInfoRes` - -```python -class ServerInfoRes(BaseModel): - min_required_weave_python_version: str -``` - + + + + +**Pydantic Fields:** + +- `min_required_weave_python_version`: `` + --- + + + ## class `StartBatchItem` - -```python -class StartBatchItem(BaseModel): - mode: str = "start" - req: tsi.CallStartReq -``` - + + + + +**Pydantic Fields:** + +- `mode`: `` +- `req`: `` + --- + + + ## class `EndBatchItem` - -```python -class EndBatchItem(BaseModel): - mode: str = "end" - req: tsi.CallEndReq -``` - + + + + +**Pydantic Fields:** + +- `mode`: `` +- `req`: `` + --- + + + ## class `Batch` - -```python -class Batch(BaseModel): - batch: t.List[t.Union[StartBatchItem, EndBatchItem]] -``` - \ No newline at end of file + + + + +**Pydantic Fields:** + +- `batch`: `typing.List[typing.Union[StartBatchItem, EndBatchItem]]` diff --git a/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.trace_server_interface.md b/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.trace_server_interface.md index e5ef06e0d83..87efbca2693 100644 --- a/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.trace_server_interface.md +++ b/docs/docs/reference/python-sdk/weave/trace_server/weave.trace_server.trace_server_interface.md @@ -34,6 +34,7 @@ sidebar_label: trace_server_interface - [`trace_server_interface.CallsQueryStatsReq`](#class-callsquerystatsreq) - [`trace_server_interface.CallsQueryStatsRes`](#class-callsquerystatsres) - [`trace_server_interface.EndedCallSchemaForInsert`](#class-endedcallschemaforinsert) +- [`trace_server_interface.ExtraKeysTypedDict`](#class-extrakeystypeddict) - [`trace_server_interface.Feedback`](#class-feedback) - [`trace_server_interface.FeedbackCreateReq`](#class-feedbackcreatereq) - [`trace_server_interface.FeedbackCreateReq`](#class-feedbackcreatereq) @@ -48,6 +49,8 @@ sidebar_label: trace_server_interface - [`trace_server_interface.FileContentReadRes`](#class-filecontentreadres) - [`trace_server_interface.FileCreateReq`](#class-filecreatereq) - [`trace_server_interface.FileCreateRes`](#class-filecreateres) +- [`trace_server_interface.LLMCostSchema`](#class-llmcostschema) +- [`trace_server_interface.LLMUsageSchema`](#class-llmusageschema) - [`trace_server_interface.ObjCreateReq`](#class-objcreatereq) - [`trace_server_interface.ObjCreateRes`](#class-objcreateres) - [`trace_server_interface.ObjQueryReq`](#class-objqueryreq) @@ -65,6 +68,8 @@ sidebar_label: trace_server_interface - [`trace_server_interface.RefsReadBatchReq`](#class-refsreadbatchreq) - [`trace_server_interface.RefsReadBatchRes`](#class-refsreadbatchres) - [`trace_server_interface.StartedCallSchemaForInsert`](#class-startedcallschemaforinsert) +- [`trace_server_interface.SummaryInsertMap`](#class-summaryinsertmap) +- [`trace_server_interface.SummaryMap`](#class-summarymap) - [`trace_server_interface.TableAppendSpec`](#class-tableappendspec) - [`trace_server_interface.TableAppendSpecPayload`](#class-tableappendspecpayload) - [`trace_server_interface.TableCreateReq`](#class-tablecreatereq) @@ -80,785 +85,1086 @@ sidebar_label: trace_server_interface - [`trace_server_interface.TableUpdateReq`](#class-tableupdatereq) - [`trace_server_interface.TableUpdateRes`](#class-tableupdateres) - [`trace_server_interface.TraceServerInterface`](#class-traceserverinterface) +- [`trace_server_interface.WeaveSummarySchema`](#class-weavesummaryschema) --- + + + ## class `CallEndReq` - -```python -class CallEndReq(BaseModel): - end: EndedCallSchemaForInsert -``` - + + + + +**Pydantic Fields:** + +- `end`: `` + --- + + + ## class `CallEndRes` - -```python -class CallEndRes(BaseModel): - pass -``` - + + + + + --- + + + ## class `CallReadReq` - -```python -class CallReadReq(BaseModel): - project_id: str - id: str -``` - + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `id`: `` +- `include_costs`: `typing.Optional[bool]` + --- + + + ## class `CallReadRes` - -```python -class CallReadRes(BaseModel): - call: typing.Optional[CallSchema] -``` - + + + + +**Pydantic Fields:** + +- `call`: `typing.Optional[CallSchema]` + --- -## class `CallSchema` - -```python -class CallSchema(BaseModel): - id: str - project_id: str - # Name of the calling function (op) - op_name: str - # Optional display name of the call - display_name: typing.Optional[str] = None + - ## Trace ID - trace_id: str - ## Parent ID is optional because the call may be a root - parent_id: typing.Optional[str] = None +## class `CallSchema` - ## Start time is required - started_at: datetime.datetime - ## Attributes: properties of the call - attributes: typing.Dict[str, typing.Any] - ## Inputs - inputs: typing.Dict[str, typing.Any] - ## End time is required if finished - ended_at: typing.Optional[datetime.datetime] = None - ## Exception is present if the call failed - exception: typing.Optional[str] = None - ## Outputs - output: typing.Optional[typing.Any] = None +**Pydantic Fields:** - ## Summary: a summary of the call - summary: typing.Optional[typing.Dict[str, typing.Any]] = None +- `id`: `` +- `project_id`: `` +- `op_name`: `` +- `display_name`: `typing.Optional[str]` +- `trace_id`: `` +- `parent_id`: `typing.Optional[str]` +- `started_at`: `` +- `attributes`: `typing.Dict[str, typing.Any]` +- `inputs`: `typing.Dict[str, typing.Any]` +- `ended_at`: `typing.Optional[datetime.datetime]` +- `exception`: `typing.Optional[str]` +- `output`: `typing.Optional[typing.Any]` +- `summary`: `typing.Optional[SummaryMap]` +- `wb_user_id`: `typing.Optional[str]` +- `wb_run_id`: `typing.Optional[str]` +- `deleted_at`: `typing.Optional[datetime.datetime]` +--- - # WB Metadata - wb_user_id: typing.Optional[str] = None - wb_run_id: typing.Optional[str] = None + - deleted_at: typing.Optional[datetime.datetime] = None +### method `serialize_typed_dicts` +```python +serialize_typed_dicts(v: Dict[str, Any]) → Dict[str, Any] ``` - + + + + + + --- + + + ## class `CallStartReq` - -```python -class CallStartReq(BaseModel): - start: StartedCallSchemaForInsert -``` - + + + + +**Pydantic Fields:** + +- `start`: `` + --- + + + ## class `CallStartRes` - -```python -class CallStartRes(BaseModel): - id: str - trace_id: str -``` - + + + + +**Pydantic Fields:** + +- `id`: `` +- `trace_id`: `` + --- + + + ## class `CallUpdateReq` - -```python -class CallUpdateReq(BaseModel): - # required for all updates - project_id: str - call_id: str - # optional update fields - display_name: typing.Optional[str] = None - # wb_user_id is automatically populated by the server - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) -``` - + + +**Pydantic Fields:** + +- `project_id`: `` +- `call_id`: `` +- `display_name`: `typing.Optional[str]` +- `wb_user_id`: `typing.Optional[str]` + --- + + + ## class `CallUpdateReq` - -```python -class CallUpdateReq(BaseModel): - # required for all updates - project_id: str - call_id: str - # optional update fields - display_name: typing.Optional[str] = None - # wb_user_id is automatically populated by the server - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) -``` - + + +**Pydantic Fields:** + +- `project_id`: `` +- `call_id`: `` +- `display_name`: `typing.Optional[str]` +- `wb_user_id`: `typing.Optional[str]` + --- + + + ## class `CallUpdateRes` - -```python -class CallUpdateRes(BaseModel): - pass -``` - + + + + + +--- + + + +## class `CallsDeleteReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `call_ids`: `typing.List[str]` +- `wb_user_id`: `typing.Optional[str]` + --- + + + ## class `CallsDeleteReq` - + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `call_ids`: `typing.List[str]` +- `wb_user_id`: `typing.Optional[str]` + +--- + + + +## class `CallsDeleteRes` + + + + + + +--- + + + +## class `CallsQueryReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `filter`: `typing.Optional[_CallsFilter]` +- `limit`: `typing.Optional[int]` +- `offset`: `typing.Optional[int]` +- `sort_by`: `typing.Optional[typing.List[_SortBy]]` +- `query`: `typing.Optional[weave.trace_server.interface.query.Query]` +- `include_costs`: `typing.Optional[bool]` +- `columns`: `typing.Optional[typing.List[str]]` + +--- + + + +## class `CallsQueryRes` + + + + + +**Pydantic Fields:** + +- `calls`: `typing.List[CallSchema]` + +--- + + + +## class `CallsQueryStatsReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `filter`: `typing.Optional[_CallsFilter]` +- `query`: `typing.Optional[weave.trace_server.interface.query.Query]` + +--- + + + +## class `CallsQueryStatsRes` + + + + + +**Pydantic Fields:** + +- `count`: `` + +--- + + + +## class `EndedCallSchemaForInsert` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `id`: `` +- `ended_at`: `` +- `exception`: `typing.Optional[str]` +- `output`: `typing.Optional[typing.Any]` +- `summary`: `` +--- + + + +### method `serialize_typed_dicts` + ```python -class CallsDeleteReq(BaseModel): - project_id: str - call_ids: typing.List[str] +serialize_typed_dicts(v: Dict[str, Any]) → Dict[str, Any] +``` + + + + + + +--- + + + +## class `ExtraKeysTypedDict` + + + + + + + + +--- + + + +## class `Feedback` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `weave_ref`: `` +- `creator`: `typing.Optional[str]` +- `feedback_type`: `` +- `payload`: `typing.Dict[str, typing.Any]` +- `wb_user_id`: `typing.Optional[str]` +- `id`: `` +- `created_at`: `` + +--- + + + +## class `FeedbackCreateReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `weave_ref`: `` +- `creator`: `typing.Optional[str]` +- `feedback_type`: `` +- `payload`: `typing.Dict[str, typing.Any]` +- `wb_user_id`: `typing.Optional[str]` + +--- + + + +## class `FeedbackCreateReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `weave_ref`: `` +- `creator`: `typing.Optional[str]` +- `feedback_type`: `` +- `payload`: `typing.Dict[str, typing.Any]` +- `wb_user_id`: `typing.Optional[str]` + +--- + + + +## class `FeedbackCreateRes` + + + + + +**Pydantic Fields:** + +- `id`: `` +- `created_at`: `` +- `wb_user_id`: `` +- `payload`: `typing.Dict[str, typing.Any]` + +--- + + + +## class `FeedbackPayloadNoteReq` + + + + + +**Pydantic Fields:** + +- `note`: `` + +--- + + + +## class `FeedbackPayloadReactionReq` + + + + + +**Pydantic Fields:** + +- `emoji`: `` + +--- + + + +## class `FeedbackPurgeReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `query`: `` + +--- + + + +## class `FeedbackPurgeRes` + + + + + + +--- + + + +## class `FeedbackQueryReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `fields`: `typing.Optional[list[str]]` +- `query`: `typing.Optional[weave.trace_server.interface.query.Query]` +- `sort_by`: `typing.Optional[typing.List[_SortBy]]` +- `limit`: `typing.Optional[int]` +- `offset`: `typing.Optional[int]` + +--- + + + +## class `FeedbackQueryRes` + + + + + +**Pydantic Fields:** + +- `result`: `list[dict[str, typing.Any]]` + +--- + + + +## class `FileContentReadReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `digest`: `` + +--- + + + +## class `FileContentReadRes` + + + + + +**Pydantic Fields:** + +- `content`: `` + +--- + + + +## class `FileCreateReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `name`: `` +- `content`: `` + +--- + + + +## class `FileCreateRes` + + + + + +**Pydantic Fields:** + +- `digest`: `` + +--- + + + +## class `LLMCostSchema` + + + + + + + + +--- + + + +## class `LLMUsageSchema` + + + + + + + + +--- + + + +## class `ObjCreateReq` + + + + + +**Pydantic Fields:** + +- `obj`: `` + +--- + + + +## class `ObjCreateRes` + + + + + +**Pydantic Fields:** + +- `digest`: `` + +--- + + + +## class `ObjQueryReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `filter`: `typing.Optional[_ObjectVersionFilter]` + +--- + + + +## class `ObjQueryRes` + + + + + +**Pydantic Fields:** + +- `objs`: `typing.List[ObjSchema]` + +--- + + + +## class `ObjReadReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `object_id`: `` +- `digest`: `` + +--- + + + +## class `ObjReadRes` + + + + + +**Pydantic Fields:** + +- `obj`: `` + +--- + + + +## class `ObjSchema` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `object_id`: `` +- `created_at`: `` +- `deleted_at`: `typing.Optional[datetime.datetime]` +- `digest`: `` +- `version_index`: `` +- `is_latest`: `` +- `kind`: `` +- `base_object_class`: `typing.Optional[str]` +- `val`: `typing.Any` + +--- + + + +## class `ObjSchemaForInsert` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `object_id`: `` +- `val`: `typing.Any` + +--- + + + +## class `OpCreateReq` + + + + + +**Pydantic Fields:** + +- `op_obj`: `` + +--- + + + +## class `OpCreateRes` + + + + + +**Pydantic Fields:** + +- `digest`: `` + +--- + + + +## class `OpQueryReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `filter`: `typing.Optional[_OpVersionFilter]` + +--- + + + +## class `OpQueryRes` + + + + + +**Pydantic Fields:** + +- `op_objs`: `typing.List[ObjSchema]` + +--- + + + +## class `OpReadReq` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `name`: `` +- `digest`: `` + +--- + + + +## class `OpReadRes` + + + + + +**Pydantic Fields:** + +- `op_obj`: `` + +--- + + + +## class `RefsReadBatchReq` + + + + + +**Pydantic Fields:** + +- `refs`: `typing.List[str]` + +--- + + + +## class `RefsReadBatchRes` + + + + + +**Pydantic Fields:** + +- `vals`: `typing.List[typing.Any]` + +--- + + + +## class `StartedCallSchemaForInsert` + + + + + +**Pydantic Fields:** + +- `project_id`: `` +- `id`: `typing.Optional[str]` +- `op_name`: `` +- `display_name`: `typing.Optional[str]` +- `trace_id`: `typing.Optional[str]` +- `parent_id`: `typing.Optional[str]` +- `started_at`: `` +- `attributes`: `typing.Dict[str, typing.Any]` +- `inputs`: `typing.Dict[str, typing.Any]` +- `wb_user_id`: `typing.Optional[str]` +- `wb_run_id`: `typing.Optional[str]` + +--- + + + +## class `SummaryInsertMap` + + + + + + + + +--- + + + +## class `SummaryMap` + + + + + + + + +--- + + + +## class `TableAppendSpec` + + + + + +**Pydantic Fields:** + +- `append`: `` + +--- + + + +## class `TableAppendSpecPayload` + + + + + +**Pydantic Fields:** + +- `row`: `dict[str, typing.Any]` + +--- + + + +## class `TableCreateReq` + + + + + +**Pydantic Fields:** + +- `table`: `` + +--- + + + +## class `TableCreateRes` + + - # wb_user_id is automatically populated by the server - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) -``` - ---- -## class `CallsDeleteReq` - -```python -class CallsDeleteReq(BaseModel): - project_id: str - call_ids: typing.List[str] - # wb_user_id is automatically populated by the server - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) +**Pydantic Fields:** -``` - ---- -## class `CallsDeleteRes` - -```python -class CallsDeleteRes(BaseModel): - pass +- `digest`: `` -``` - --- -## class `CallsQueryReq` - -```python -class CallsQueryReq(BaseModel): - project_id: str - filter: typing.Optional[_CallsFilter] = None - limit: typing.Optional[int] = None - offset: typing.Optional[int] = None - # Sort by multiple fields - sort_by: typing.Optional[typing.List[_SortBy]] = None - query: typing.Optional[Query] = None - - # TODO: type this with call schema columns, following the same rules as - # _SortBy and thus GetFieldOperator.get_field_ (without direction) - columns: typing.Optional[typing.List[str]] = None -``` - ---- -## class `CallsQueryRes` - -```python -class CallsQueryRes(BaseModel): - calls: typing.List[CallSchema] + -``` - ---- -## class `CallsQueryStatsReq` - -```python -class CallsQueryStatsReq(BaseModel): - project_id: str - filter: typing.Optional[_CallsFilter] = None - query: typing.Optional[Query] = None +## class `TableInsertSpec` -``` - ---- -## class `CallsQueryStatsRes` - -```python -class CallsQueryStatsRes(BaseModel): - count: int -``` - ---- -## class `EndedCallSchemaForInsert` - -```python -class EndedCallSchemaForInsert(BaseModel): - project_id: str - id: str - ## End time is required - ended_at: datetime.datetime - ## Exception is present if the call failed - exception: typing.Optional[str] = None - ## Outputs - output: typing.Optional[typing.Any] = None +**Pydantic Fields:** - ## Summary: a summary of the call - summary: typing.Dict[str, typing.Any] +- `insert`: `` -``` - --- -## class `Feedback` + + +## class `TableInsertSpecPayload` +**Pydantic Fields:** + +- `index`: `` +- `row`: `dict[str, typing.Any]` + --- -#### property model_extra + -Get extra fields set during validation. +## class `TablePopSpec` -**Returns:** - A dictionary of extra fields, or `None` if `config.extra` is not set to `"allow"`. ---- -#### property model_fields_set +**Pydantic Fields:** -Returns the set of fields that have been explicitly set on this model instance. +- `pop`: `` +--- + -**Returns:** - A set of strings representing the fields that have been set, i.e. that were not filled from defaults. +## class `TablePopSpecPayload` ---- -## class `FeedbackCreateReq` - -```python -class FeedbackCreateReq(BaseModel): - project_id: str = Field(examples=["entity/project"]) - weave_ref: str = Field(examples=["weave:///entity/project/object/name:digest"]) - creator: typing.Optional[str] = Field(default=None, examples=["Jane Smith"]) - feedback_type: str = Field(examples=["custom"]) - payload: typing.Dict[str, typing.Any] = Field( - examples=[ - { - "key": "value", - } - ] - ) - - # wb_user_id is automatically populated by the server - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) -``` - ---- -## class `FeedbackCreateReq` - -```python -class FeedbackCreateReq(BaseModel): - project_id: str = Field(examples=["entity/project"]) - weave_ref: str = Field(examples=["weave:///entity/project/object/name:digest"]) - creator: typing.Optional[str] = Field(default=None, examples=["Jane Smith"]) - feedback_type: str = Field(examples=["custom"]) - payload: typing.Dict[str, typing.Any] = Field( - examples=[ - { - "key": "value", - } - ] - ) - - # wb_user_id is automatically populated by the server - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) +**Pydantic Fields:** -``` - ---- -## class `FeedbackCreateRes` - -```python -class FeedbackCreateRes(BaseModel): - id: str - created_at: datetime.datetime - wb_user_id: str - payload: typing.Dict[str, typing.Any] # If not empty, replace payload +- `index`: `` -``` - --- -## class `FeedbackPayloadNoteReq` - -```python -class FeedbackPayloadNoteReq(BaseModel): - note: str = Field(min_length=1, max_length=1024) -``` - ---- -## class `FeedbackPayloadReactionReq` - -```python -class FeedbackPayloadReactionReq(BaseModel): - emoji: str + -``` - ---- -## class `FeedbackPurgeReq` - -```python -class FeedbackPurgeReq(BaseModel): - project_id: str = Field(examples=["entity/project"]) - query: Query +## class `TableQueryReq` -``` - ---- -## class `FeedbackPurgeRes` - -```python -class FeedbackPurgeRes(BaseModel): - pass -``` - ---- -## class `FeedbackQueryReq` - -```python -class FeedbackQueryReq(BaseModel): - project_id: str = Field(examples=["entity/project"]) - fields: typing.Optional[list[str]] = Field( - default=None, examples=[["id", "feedback_type", "payload.note"]] - ) - query: typing.Optional[Query] = None - # TODO: I think I would prefer to call this order_by to match SQL, but this is what calls API uses - # TODO: Might be nice to have shortcut for single field and implied ASC direction - # TODO: I think _SortBy shouldn't have leading underscore - sort_by: typing.Optional[typing.List[_SortBy]] = None - limit: typing.Optional[int] = Field(default=None, examples=[10]) - offset: typing.Optional[int] = Field(default=None, examples=[0]) -``` - ---- -## class `FeedbackQueryRes` - -```python -class FeedbackQueryRes(BaseModel): - # Note: this is not a list of Feedback because user can request any fields. - result: list[dict[str, typing.Any]] -``` - ---- -## class `FileContentReadReq` - -```python -class FileContentReadReq(BaseModel): - project_id: str - digest: str -``` - ---- -## class `FileContentReadRes` - -```python -class FileContentReadRes(BaseModel): - content: bytes +**Pydantic Fields:** -``` - ---- -## class `FileCreateReq` - -```python -class FileCreateReq(BaseModel): - project_id: str - name: str - content: bytes +- `project_id`: `` +- `digest`: `` +- `filter`: `typing.Optional[_TableRowFilter]` +- `limit`: `typing.Optional[int]` +- `offset`: `typing.Optional[int]` -``` - --- -## class `FileCreateRes` - -```python -class FileCreateRes(BaseModel): - digest: str -``` - ---- -## class `ObjCreateReq` - -```python -class ObjCreateReq(BaseModel): - obj: ObjSchemaForInsert + -``` - ---- -## class `ObjCreateRes` - -```python -class ObjCreateRes(BaseModel): - digest: str # +## class `TableQueryRes` -``` - ---- -## class `ObjQueryReq` - -```python -class ObjQueryReq(BaseModel): - project_id: str - filter: typing.Optional[_ObjectVersionFilter] = None -``` - ---- -## class `ObjQueryRes` - -```python -class ObjQueryRes(BaseModel): - objs: typing.List[ObjSchema] -``` - ---- -## class `ObjReadReq` - -```python -class ObjReadReq(BaseModel): - project_id: str - object_id: str - digest: str -``` - ---- -## class `ObjReadRes` - -```python -class ObjReadRes(BaseModel): - obj: ObjSchema -``` - ---- -## class `ObjSchema` - -```python -class ObjSchema(BaseModel): - project_id: str - object_id: str - created_at: datetime.datetime - deleted_at: typing.Optional[datetime.datetime] = None - digest: str - version_index: int - is_latest: int - kind: str - base_object_class: typing.Optional[str] - val: typing.Any +**Pydantic Fields:** -``` - ---- -## class `ObjSchemaForInsert` - -```python -class ObjSchemaForInsert(BaseModel): - project_id: str - object_id: str - val: typing.Any +- `rows`: `typing.List[TableRowSchema]` -``` - --- -## class `OpCreateReq` - -```python -class OpCreateReq(BaseModel): - op_obj: ObjSchemaForInsert -``` - ---- -## class `OpCreateRes` - -```python -class OpCreateRes(BaseModel): - digest: str + -``` - ---- -## class `OpQueryReq` - -```python -class OpQueryReq(BaseModel): - project_id: str - filter: typing.Optional[_OpVersionFilter] = None +## class `TableRowSchema` -``` - ---- -## class `OpQueryRes` - -```python -class OpQueryRes(BaseModel): - op_objs: typing.List[ObjSchema] -``` - ---- -## class `OpReadReq` - -```python -class OpReadReq(BaseModel): - project_id: str - name: str - digest: str -``` - ---- -## class `OpReadRes` - -```python -class OpReadRes(BaseModel): - op_obj: ObjSchema -``` - ---- -## class `RefsReadBatchReq` - -```python -class RefsReadBatchReq(BaseModel): - refs: typing.List[str] -``` - ---- -## class `RefsReadBatchRes` - -```python -class RefsReadBatchRes(BaseModel): - vals: typing.List[typing.Any] +**Pydantic Fields:** + +- `digest`: `` +- `val`: `typing.Any` -``` - --- -## class `StartedCallSchemaForInsert` - -```python -class StartedCallSchemaForInsert(BaseModel): - project_id: str - id: typing.Optional[str] = None # Will be generated if not provided - # Name of the calling function (op) - op_name: str - # Optional display name of the call - display_name: typing.Optional[str] = None + - ## Trace ID - trace_id: typing.Optional[str] = None # Will be generated if not provided - ## Parent ID is optional because the call may be a root - parent_id: typing.Optional[str] = None +## class `TableSchemaForInsert` - ## Start time is required - started_at: datetime.datetime - ## Attributes: properties of the call - attributes: typing.Dict[str, typing.Any] - ## Inputs - inputs: typing.Dict[str, typing.Any] - # WB Metadata - wb_user_id: typing.Optional[str] = Field(None, description=WB_USER_ID_DESCRIPTION) - wb_run_id: typing.Optional[str] = None -``` - ---- -## class `TableAppendSpec` - -```python -class TableAppendSpec(BaseModel): - append: TableAppendSpecPayload -``` - ---- -## class `TableAppendSpecPayload` - -```python -class TableAppendSpecPayload(BaseModel): - row: dict[str, typing.Any] +**Pydantic Fields:** -``` - ---- -## class `TableCreateReq` - -```python -class TableCreateReq(BaseModel): - table: TableSchemaForInsert +- `project_id`: `` +- `rows`: `list[dict[str, typing.Any]]` -``` - --- -## class `TableCreateRes` - -```python -class TableCreateRes(BaseModel): - digest: str -``` - ---- -## class `TableInsertSpec` - -```python -class TableInsertSpec(BaseModel): - insert: TableInsertSpecPayload + -``` - ---- -## class `TableInsertSpecPayload` - -```python -class TableInsertSpecPayload(BaseModel): - index: int - row: dict[str, typing.Any] +## class `TableUpdateReq` -``` - ---- -## class `TablePopSpec` - -```python -class TablePopSpec(BaseModel): - pop: TablePopSpecPayload -``` - ---- -## class `TablePopSpecPayload` - -```python -class TablePopSpecPayload(BaseModel): - index: int -``` - ---- -## class `TableQueryReq` - -```python -class TableQueryReq(BaseModel): - project_id: str - digest: str - filter: typing.Optional[_TableRowFilter] = None - limit: typing.Optional[int] = None - offset: typing.Optional[int] = None -``` - ---- -## class `TableQueryRes` - -```python -class TableQueryRes(BaseModel): - rows: typing.List[TableRowSchema] -``` - ---- -## class `TableRowSchema` - -```python -class TableRowSchema(BaseModel): - digest: str - val: typing.Any +**Pydantic Fields:** -``` - ---- -## class `TableSchemaForInsert` - -```python -class TableSchemaForInsert(BaseModel): - project_id: str - rows: list[dict[str, typing.Any]] +- `project_id`: `` +- `base_digest`: `` +- `updates`: `list[typing.Union[TableAppendSpec, TablePopSpec, TableInsertSpec]]` -``` - --- -## class `TableUpdateReq` - -```python -class TableUpdateReq(BaseModel): - project_id: str - base_digest: str - updates: list[TableUpdateSpec] -``` - ---- + + ## class `TableUpdateRes` - -```python -class TableUpdateRes(BaseModel): - digest: str -``` - + + + + +**Pydantic Fields:** + +- `digest`: `` + --- + + ## class `TraceServerInterface` @@ -869,6 +1175,8 @@ class TableUpdateRes(BaseModel): --- + + ### method `call_end` ```python @@ -881,6 +1189,8 @@ call_end(req: CallEndReq) → CallEndRes --- + + ### method `call_read` ```python @@ -893,6 +1203,8 @@ call_read(req: CallReadReq) → CallReadRes --- + + ### method `call_start` ```python @@ -905,6 +1217,8 @@ call_start(req: CallStartReq) → CallStartRes --- + + ### method `call_update` ```python @@ -917,6 +1231,8 @@ call_update(req: CallUpdateReq) → CallUpdateRes --- + + ### method `calls_delete` ```python @@ -929,6 +1245,8 @@ calls_delete(req: CallsDeleteReq) → CallsDeleteRes --- + + ### method `calls_query` ```python @@ -941,6 +1259,8 @@ calls_query(req: CallsQueryReq) → CallsQueryRes --- + + ### method `calls_query_stats` ```python @@ -953,6 +1273,8 @@ calls_query_stats(req: CallsQueryStatsReq) → CallsQueryStatsRes --- + + ### method `calls_query_stream` ```python @@ -965,6 +1287,8 @@ calls_query_stream(req: CallsQueryReq) → Iterator[CallSchema] --- + + ### method `ensure_project_exists` ```python @@ -977,6 +1301,8 @@ ensure_project_exists(entity: str, project: str) → None --- + + ### method `feedback_create` ```python @@ -989,6 +1315,8 @@ feedback_create(req: FeedbackCreateReq) → FeedbackCreateRes --- + + ### method `feedback_purge` ```python @@ -1001,6 +1329,8 @@ feedback_purge(req: FeedbackPurgeReq) → FeedbackPurgeRes --- + + ### method `feedback_query` ```python @@ -1013,6 +1343,8 @@ feedback_query(req: FeedbackQueryReq) → FeedbackQueryRes --- + + ### method `file_content_read` ```python @@ -1025,6 +1357,8 @@ file_content_read(req: FileContentReadReq) → FileContentReadRes --- + + ### method `file_create` ```python @@ -1037,6 +1371,8 @@ file_create(req: FileCreateReq) → FileCreateRes --- + + ### method `obj_create` ```python @@ -1049,6 +1385,8 @@ obj_create(req: ObjCreateReq) → ObjCreateRes --- + + ### method `obj_read` ```python @@ -1061,6 +1399,8 @@ obj_read(req: ObjReadReq) → ObjReadRes --- + + ### method `objs_query` ```python @@ -1073,6 +1413,8 @@ objs_query(req: ObjQueryReq) → ObjQueryRes --- + + ### method `op_create` ```python @@ -1085,6 +1427,8 @@ op_create(req: OpCreateReq) → OpCreateRes --- + + ### method `op_read` ```python @@ -1097,6 +1441,8 @@ op_read(req: OpReadReq) → OpReadRes --- + + ### method `ops_query` ```python @@ -1109,6 +1455,8 @@ ops_query(req: OpQueryReq) → OpQueryRes --- + + ### method `refs_read_batch` ```python @@ -1121,6 +1469,8 @@ refs_read_batch(req: RefsReadBatchReq) → RefsReadBatchRes --- + + ### method `table_create` ```python @@ -1133,6 +1483,8 @@ table_create(req: TableCreateReq) → TableCreateRes --- + + ### method `table_query` ```python @@ -1145,6 +1497,8 @@ table_query(req: TableQueryReq) → TableQueryRes --- + + ### method `table_update` ```python @@ -1155,3 +1509,16 @@ table_update(req: TableUpdateReq) → TableUpdateRes + +--- + + + +## class `WeaveSummarySchema` + + + + + + + diff --git a/docs/docs/reference/python-sdk/weave/weave.feedback.md b/docs/docs/reference/python-sdk/weave/weave.feedback.md index 387b69079da..b715f3bb1cf 100644 --- a/docs/docs/reference/python-sdk/weave/weave.feedback.md +++ b/docs/docs/reference/python-sdk/weave/weave.feedback.md @@ -26,9 +26,13 @@ Classes for working with feedback on a project or ref level. --- + + ## class `Feedbacks` A collection of Feedback objects with utilities. + + ### method `__init__` ```python @@ -44,6 +48,8 @@ __init__(show_refs: bool, feedbacks: Optional[Iterable[Feedback]] = None) → No --- + + ### method `refs` ```python @@ -55,9 +61,13 @@ Return the unique refs associated with these feedbacks. --- + + ## class `FeedbackQuery` Lazy-loading object for fetching feedback from the server. + + ### method `__init__` ```python @@ -80,6 +90,8 @@ __init__( --- + + ### method `execute` ```python @@ -92,6 +104,8 @@ execute() → Feedbacks --- + + ### method `refresh` ```python @@ -104,6 +118,8 @@ refresh() → Feedbacks --- + + ### method `refs` ```python @@ -117,9 +133,13 @@ refs() → Refs --- + + ## class `RefFeedbackQuery` Object for interacting with feedback associated with a particular ref. + + ### method `__init__` ```python @@ -135,6 +155,8 @@ __init__(ref: str) → None --- + + ### method `add` ```python @@ -152,6 +174,8 @@ feedback_type: A string identifying the type of feedback. The "wandb." prefix is --- + + ### method `add_note` ```python @@ -164,6 +188,8 @@ add_note(note: str, creator: Optional[str] = None) → str --- + + ### method `add_reaction` ```python @@ -176,6 +202,8 @@ add_reaction(emoji: str, creator: Optional[str] = None) → str --- + + ### method `execute` ```python @@ -188,6 +216,8 @@ execute() → Feedbacks --- + + ### method `purge` ```python @@ -200,6 +230,8 @@ purge(feedback_id: str) → None --- + + ### method `refresh` ```python @@ -212,6 +244,8 @@ refresh() → Feedbacks --- + + ### method `refs` ```python diff --git a/docs/docs/reference/python-sdk/weave/weave.weave_client.md b/docs/docs/reference/python-sdk/weave/weave.weave_client.md index e8d5765fcb9..4db495e8412 100644 --- a/docs/docs/reference/python-sdk/weave/weave.weave_client.md +++ b/docs/docs/reference/python-sdk/weave/weave.weave_client.md @@ -26,11 +26,15 @@ sidebar_label: weave_client --- + + ## class `WeaveClient` + + ### method `__init__` ```python @@ -51,10 +55,12 @@ __init__( --- + + ### method `call` ```python -call(call_id: str) → WeaveObject +call(call_id: str, include_costs: Optional[bool] = False) → WeaveObject ``` @@ -63,10 +69,15 @@ call(call_id: str) → WeaveObject --- + + ### method `calls` ```python -calls(filter: Optional[_CallsFilter] = None) → CallsIter +calls( + filter: Optional[_CallsFilter] = None, + include_costs: Optional[bool] = False +) → CallsIter ``` @@ -75,6 +86,8 @@ calls(filter: Optional[_CallsFilter] = None) → CallsIter --- + + ### method `create_call` ```python @@ -108,6 +121,8 @@ Create, log, and push a call onto the runtime stack. --- + + ### method `delete_call` ```python @@ -120,6 +135,8 @@ delete_call(call: Call) → None --- + + ### method `fail_call` ```python @@ -130,6 +147,8 @@ Fail a call with an exception. This is a convenience method for finish_call. --- + + ### method `feedback` ```python @@ -172,6 +191,8 @@ Query project for feedback. --- + + ### method `finish_call` ```python @@ -188,6 +209,8 @@ finish_call( --- + + ### method `get` ```python @@ -200,6 +223,8 @@ get(ref: ObjectRef) → Any --- + + ### method `save` ```python @@ -213,9 +238,13 @@ save(val: Any, name: str, branch: str = 'latest') → Any --- + + ## class `Call` Call(op_name: str, trace_id: str, project_id: str, parent_id: Optional[str], inputs: dict, id: Optional[str] = None, output: Any = None, exception: Optional[str] = None, summary: Optional[dict] = None, display_name: Optional[str] = None, attributes: Optional[dict] = None, _children: list['Call'] = <factory>, _feedback: Optional[weave.feedback.RefFeedbackQuery] = None) + + ### method `__init__` ```python @@ -261,6 +290,8 @@ __init__( --- + + ### method `children` ```python @@ -273,6 +304,8 @@ children() → CallsIter --- + + ### method `delete` ```python @@ -285,6 +318,8 @@ delete() → bool --- + + ### method `remove_display_name` ```python @@ -297,6 +332,8 @@ remove_display_name() → None --- + + ### method `set_display_name` ```python @@ -310,18 +347,23 @@ set_display_name(name: Optional[str]) → None --- + + ## class `CallsIter` + + ### method `__init__` ```python __init__( server: TraceServerInterface, project_id: str, - filter: _CallsFilter + filter: _CallsFilter, + include_costs: bool = False ) → None ``` diff --git a/docs/scripts/generate_python_sdk_docs.py b/docs/scripts/generate_python_sdk_docs.py index 05ef3567b21..cbe040b9760 100644 --- a/docs/scripts/generate_python_sdk_docs.py +++ b/docs/scripts/generate_python_sdk_docs.py @@ -1,7 +1,6 @@ # Run this to re-generate Weave API docs from code. -import inspect import os import re @@ -29,10 +28,50 @@ def markdown_description(module): return module.__doc__ or "" -def sanitize_markdown(text): +def fix_factor(text): + # When we have a field whose default is a factor function, the + # emitted payload is ``, which breaks the markdown parser. return text.replace("", "<factory>") +def fix_imgs(text): + # Images (used for source code tags) are not closed. While many + # html parsers handle this, the markdown parser does not. This + # function fixes that. + # Example: + # + # becomes + # + + # This regex matches the img tag and captures the attributes + # and the src attribute. + pattern = r'' + + # This function replaces the match with the same match, but with + # a closing slash before the closing bracket. + def replace_with_slash(match): + return f"" + + # Replace all occurrences of the pattern with the function + text = re.sub(pattern, replace_with_slash, text) + + return text + + +def fix_style(text): + # The docgen produces a lot of inline styles, which are not + # supported by the markdown parser. + find = ' style="float:right;"' + replace = "" + text = text.replace(find, replace) + + return text + + +def sanitize_markdown(text): + return fix_style(fix_imgs(fix_factor(text))) + + def remove_empty_overview_sections(overview): overview = overview.replace( """## Functions @@ -75,9 +114,76 @@ def replace_with_empty(match): return re.sub(pattern, replace_with_empty, text, flags=re.MULTILINE) -def generate_module_doc_string(module): - generator = lazydocs.MarkdownGenerator(remove_package_prefix=True) +def find_and_replace(text, start, end, replace_with, end_optional=False): + start_idx = text.find(start) + if start_idx == -1: + return text + end_idx = text.find(end, start_idx + len(start)) + if end_idx == -1: + if not end_optional: + return text + else: + end_idx = len(text) + else: + end_idx += len(end) + after = text[:start_idx] + replace_with + text[end_idx:] + return after + + +def fix_pydantic_model(text, obj, module_name): + # First, remove these properties that are not useful in the docs + search_for = """--- + +#### property model_extra""" + up_to = """---""" + text = find_and_replace(text, search_for, up_to, "---") + search_for = """--- + +#### property model_fields_set""" + up_to = """---""" + text = find_and_replace(text, search_for, up_to, "---", end_optional=True) + + text = text.replace( + """--- +---""", + "---", + ) + + # Next, pydantic does not emit good properties. Fixing that with a dump of the fields: + # This could be improved in the future + search_for = """## class""" + start_idx = text.find(search_for) + end_idx = text.find("""---""", start_idx) + + field_summary = "**Pydantic Fields:**\n\n" + if obj.model_fields: + for k, v in obj.model_fields.items(): + name = k + if hasattr(v, "alias") and v.alias != None: + name = v.alias + annotation = "Any" + if hasattr(v, "annotation") and v.annotation != None: + annotation = str(v.annotation) + annotation = annotation.replace(module_name + ".", "") + + field_summary += f"- `{name}`: `{annotation}`\n" + + text = text[:end_idx] + field_summary + text[end_idx:] + + if text.endswith("---"): + text = text[:-3] + + return text + + +def generate_module_doc_string(module, src_root_path): + generator = lazydocs.MarkdownGenerator( + src_base_url="https://github.com/wandb/weave/blob/master", + src_root_path=src_root_path, + remove_package_prefix=True, + ) markdown_paragraphs = [] + module_name = module.__name__ # We look for the special __docspec__ attribute, which lists what we want # to document, in order. @@ -85,22 +191,11 @@ def generate_module_doc_string(module): def process_item(obj): # Very special / hacky handling of pydantic models # since the lazydocs library doesn't handle them well. - if ( - isinstance(obj, type) - and issubclass(obj, pydantic.BaseModel) - and obj.__mro__[1] == pydantic.BaseModel - ): - _ = generator.class2md(obj) - text = f"""## class `{obj.__name__}` - -```python -{inspect.getsource(obj)} -``` - """ - markdown_paragraphs.append(text) - return - - if callable(obj) and not isinstance(obj, type): + if isinstance(obj, type) and issubclass(obj, pydantic.BaseModel): + markdown_paragraphs.append( + fix_pydantic_model(generator.class2md(obj), obj, module_name) + ) + elif callable(obj) and not isinstance(obj, type): markdown_paragraphs.append(generator.func2md(obj)) elif isinstance(obj, type): markdown_paragraphs.append(generator.class2md(obj)) @@ -117,7 +212,7 @@ def process_item(obj): obj = getattr(module, symbol) - if hasattr(obj, "__module__") and obj.__module__ != module.__name__: + if hasattr(obj, "__module__") and obj.__module__ != module_name: continue process_item(obj) @@ -129,7 +224,7 @@ def process_item(obj): sections = [sanitize_markdown(par) for par in markdown_paragraphs] final = "\n\n".join( [ - markdown_header(module, module.__name__.split(".")[-1]), + markdown_header(module, module_name.split(".")[-1]), markdown_title(module), markdown_description(module), SECTION_SEPARATOR, @@ -142,13 +237,13 @@ def process_item(obj): return final -def doc_module_to_file(module, output_path): - api_docs = generate_module_doc_string(module) +def doc_module_to_file(module, output_path, module_root_path=None): + api_docs = generate_module_doc_string(module, module_root_path) with open(output_path, "w") as f: f.write(api_docs) -def doc_module(module, root_path="./docs/reference/python-sdk"): +def doc_module(module, root_path="./docs/reference/python-sdk", module_root_path=None): module_path = module.__name__ path_parts = module_path.split(".") file_name = module_path + ".md" @@ -162,7 +257,7 @@ def doc_module(module, root_path="./docs/reference/python-sdk"): target_path = target_dir + "/" + file_name os.makedirs(target_dir, exist_ok=True) - doc_module_to_file(module, target_path) + doc_module_to_file(module, target_path, module_root_path) def main(): @@ -176,14 +271,18 @@ def main(): ) from weave.trace_server.interface import query - # TODO: It would be nice to just walk the module hierarchy and generate docs for all modules - doc_module(weave) - doc_module(client) - doc_module(remote_http_trace_server) - doc_module(trace_server_interface) - doc_module(query) - doc_module(feedback) - doc_module(util) + module_root_path = weave.__file__.split("/weave/__init__.py")[0] + for module in [ + # TODO: It would be nice to just walk the module hierarchy and generate docs for all modules + weave, + client, + remote_http_trace_server, + trace_server_interface, + query, + feedback, + util, + ]: + doc_module(module, module_root_path=module_root_path) if __name__ == "__main__":