From f92b4464fd0c8def3417f3c46f3819fe3c4e5fc8 Mon Sep 17 00:00:00 2001 From: Brian Greunke Date: Thu, 8 May 2025 18:48:37 -0500 Subject: [PATCH 1/4] docs: updated docs with latest API --- docs/docs.json | 41 ++ docs/dreadnode/api.mdx | 12 + docs/dreadnode/api/client.mdx | 106 ++++ docs/dreadnode/api/models.mdx | 617 +++++++++++++++++++++ docs/dreadnode/artifact.mdx | 12 + docs/dreadnode/artifact/merger.mdx | 61 +++ docs/dreadnode/artifact/storage.mdx | 103 ++++ docs/dreadnode/artifact/tree_builder.mdx | 90 ++++ docs/dreadnode/constants.mdx | 12 + docs/dreadnode/integrations.mdx | 12 + docs/dreadnode/main.mdx | 384 +++++++++++++ docs/dreadnode/metric.mdx | 137 +++++ docs/dreadnode/object.mdx | 114 ++++ docs/dreadnode/serialization.mdx | 68 +++ docs/dreadnode/task.mdx | 308 +++++++++++ docs/dreadnode/tracing.mdx | 12 + docs/dreadnode/tracing/constants.mdx | 12 + docs/dreadnode/tracing/exporters.mdx | 219 ++++++++ docs/dreadnode/tracing/span.mdx | 652 +++++++++++++++++++++++ docs/dreadnode/types.mdx | 28 + docs/dreadnode/util.mdx | 35 ++ docs/dreadnode/version.mdx | 12 + 22 files changed, 3047 insertions(+) create mode 100644 docs/docs.json create mode 100644 docs/dreadnode/api.mdx create mode 100644 docs/dreadnode/api/client.mdx create mode 100644 docs/dreadnode/api/models.mdx create mode 100644 docs/dreadnode/artifact.mdx create mode 100644 docs/dreadnode/artifact/merger.mdx create mode 100644 docs/dreadnode/artifact/storage.mdx create mode 100644 docs/dreadnode/artifact/tree_builder.mdx create mode 100644 docs/dreadnode/constants.mdx create mode 100644 docs/dreadnode/integrations.mdx create mode 100644 docs/dreadnode/main.mdx create mode 100644 docs/dreadnode/metric.mdx create mode 100644 docs/dreadnode/object.mdx create mode 100644 docs/dreadnode/serialization.mdx create mode 100644 docs/dreadnode/task.mdx create mode 100644 docs/dreadnode/tracing.mdx create mode 100644 docs/dreadnode/tracing/constants.mdx create mode 100644 docs/dreadnode/tracing/exporters.mdx create mode 100644 docs/dreadnode/tracing/span.mdx create mode 100644 docs/dreadnode/types.mdx create mode 100644 docs/dreadnode/util.mdx create mode 100644 docs/dreadnode/version.mdx diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 00000000..37e8d1c7 --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,41 @@ +{ + "group": "API Reference", + "pages": [ + { + "group": "api", + "pages": [ + "strikes/library/api/client", + "strikes/library/api", + "strikes/library/api/models" + ] + }, + { + "group": "artifact", + "pages": [ + "strikes/library/artifact", + "strikes/library/artifact/merger", + "strikes/library/artifact/storage", + "strikes/library/artifact/tree_builder" + ] + }, + "strikes/library/constants", + "strikes/library/integrations", + "strikes/library/main", + "strikes/library/metric", + "strikes/library/object", + "strikes/library/serialization", + "strikes/library/task", + { + "group": "tracing", + "pages": [ + "strikes/library/tracing/constants", + "strikes/library/tracing/exporters", + "strikes/library/tracing", + "strikes/library/tracing/span" + ] + }, + "strikes/library/types", + "strikes/library/util", + "strikes/library/version" + ] +} \ No newline at end of file diff --git a/docs/dreadnode/api.mdx b/docs/dreadnode/api.mdx new file mode 100644 index 00000000..519fb648 --- /dev/null +++ b/docs/dreadnode/api.mdx @@ -0,0 +1,12 @@ +--- +title: 'api' +sidebarTitle: 'api' +groups: ["strikes"] +--- + +# Module `api` + +*(Full name: `dreadnode.api`)* + +**Source file:** `__init__.py` + diff --git a/docs/dreadnode/api/client.mdx b/docs/dreadnode/api/client.mdx new file mode 100644 index 00000000..0a35b111 --- /dev/null +++ b/docs/dreadnode/api/client.mdx @@ -0,0 +1,106 @@ +--- +title: 'client' +sidebarTitle: 'client' +groups: ["strikes"] +--- + +# Module `client` + +*(Full name: `dreadnode.api.client`)* + +**Source file:** `client.py` + +## Classes + + +### Class `ApiClient` + +**Inherits from:** `object` + +Client for the Dreadnode API. + +#### Methods + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `export_metrics` + +`export_metrics(...)` + +--- + +##### `export_parameters` + +`export_parameters(...)` + +--- + +##### `export_runs` + +`export_runs(...)` + +--- + +##### `export_timeseries` + +`export_timeseries(...)` + +--- + +##### `get_project` + +`get_project(...)` + +--- + +##### `get_run` + +`get_run(...)` + +--- + +##### `get_run_tasks` + +`get_run_tasks(...)` + +--- + +##### `get_run_trace` + +`get_run_trace(...)` + +--- + +##### `get_user_data_credentials` + +`get_user_data_credentials(...)` + +--- + +##### `list_projects` + +`list_projects(...)` + +--- + +##### `list_runs` + +`list_runs(...)` + +--- + +##### `request` + +`request(...)` + +Make a request to the API. Raise an exception for non-200 status codes. + +--- + + diff --git a/docs/dreadnode/api/models.mdx b/docs/dreadnode/api/models.mdx new file mode 100644 index 00000000..b9c09f51 --- /dev/null +++ b/docs/dreadnode/api/models.mdx @@ -0,0 +1,617 @@ +--- +title: 'models' +sidebarTitle: 'models' +groups: ["strikes"] +--- + +# Module `models` + +*(Full name: `dreadnode.api.models`)* + +**Source file:** `models.py` + +## Classes + + +### Class `Metric` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `ObjectRef` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `ObjectUri` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `ObjectVal` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `Project` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `Run` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `SpanEvent` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `SpanException` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `SpanLink` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `SpanTree` + +**Inherits from:** `pydantic.main.BaseModel` + +Tree representation of a trace span with its children + + +### Class `Task` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `TaskTree` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `TraceLog` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `TraceSpan` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `UserAPIKey` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `UserDataCredentials` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `UserResponse` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + +### Class `V0Object` + +**Inherits from:** `pydantic.main.BaseModel` + +!!! abstract "Usage Documentation" + +[Models](../concepts/models.md) + +A base class for creating Pydantic models. + +**Parameters:** + +- **`__class_vars__`**: The names of the class variables defined on the model. +- **`__private_attributes__`**: Metadata about the private attributes of the model. +- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. +- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. +- **`__pydantic_core_schema__`**: The core schema of the model. +- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. +- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. +This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. +- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to +__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. +- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. +- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. +- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. +- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. +- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. +- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. +- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. +- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] +is set to `'allow'`. +- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. +- **`__pydantic_private__`**: Values of private attributes set on the model instance. + + diff --git a/docs/dreadnode/artifact.mdx b/docs/dreadnode/artifact.mdx new file mode 100644 index 00000000..cdb34c1d --- /dev/null +++ b/docs/dreadnode/artifact.mdx @@ -0,0 +1,12 @@ +--- +title: 'artifact' +sidebarTitle: 'artifact' +groups: ["strikes"] +--- + +# Module `artifact` + +*(Full name: `dreadnode.artifact`)* + +**Source file:** `__init__.py` + diff --git a/docs/dreadnode/artifact/merger.mdx b/docs/dreadnode/artifact/merger.mdx new file mode 100644 index 00000000..b0562276 --- /dev/null +++ b/docs/dreadnode/artifact/merger.mdx @@ -0,0 +1,61 @@ +--- +title: 'merger' +sidebarTitle: 'merger' +groups: ["strikes"] +--- + +# Module `merger` + +*(Full name: `dreadnode.artifact.merger`)* + +**Source file:** `merger.py` + +Utility for merging artifact tree structures while preserving directory hierarchy. + +## Classes + + +### Class `ArtifactMerger` + +**Inherits from:** `object` + +Class responsible for merging artifact tree structures. + +Handles overlapping directory structures and efficiently combines artifacts. + +#### Methods + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `add_tree` + +`add_tree(...)` + +Add a new artifact tree, merging with existing trees if needed. + +This method analyzes the new tree and determines how to integrate it +with existing trees, handling parent/child relationships and overlaps. + +**Parameters:** + +- **`new_tree`**: New directory tree to add + +--- + +##### `get_merged_trees` + +`get_merged_trees(...)` + +Get the current merged trees. + +**Returns:** List of merged directory trees + +--- + + diff --git a/docs/dreadnode/artifact/storage.mdx b/docs/dreadnode/artifact/storage.mdx new file mode 100644 index 00000000..7b980135 --- /dev/null +++ b/docs/dreadnode/artifact/storage.mdx @@ -0,0 +1,103 @@ +--- +title: 'storage' +sidebarTitle: 'storage' +groups: ["strikes"] +--- + +# Module `storage` + +*(Full name: `dreadnode.artifact.storage`)* + +**Source file:** `storage.py` + +Artifact storage implementation for fsspec-compatible file systems. + +Provides efficient uploading of files and directories with deduplication. + +## Classes + + +### Class `ArtifactStorage` + +**Inherits from:** `object` + +Storage for artifacts with efficient handling of large files and directories. + +Supports: +- Content-based deduplication using SHA1 hashing +- Batch uploads for directories handled by fsspec + +#### Methods + +##### `__init__` + +`__init__(...)` + +Initialize artifact storage with a file system and prefix path. + +**Parameters:** + +- **`file_system`**: FSSpec-compatible file system + +--- + +##### `batch_upload_files` + +`batch_upload_files(...)` + +Upload multiple files in a single batch operation. + +**Parameters:** + +- **`source_paths`**: List of local file paths +- **`target_paths`**: List of target keys/paths + +**Returns:** List of URIs for the uploaded files + +--- + +##### `compute_file_hash` + +`compute_file_hash(...)` + +Compute SHA1 hash of a file, using streaming only for larger files. + +**Parameters:** + +- **`file_path`**: Path to the file +- **`stream_threshold_mb`**: Size threshold in MB for streaming vs. loading whole file + +**Returns:** First 16 chars of SHA1 hash + +--- + +##### `compute_file_hashes` + +`compute_file_hashes(...)` + +Compute SHA1 hashes for multiple files. + +**Parameters:** + +- **`file_paths`**: List of file paths to hash + +**Returns:** Dictionary mapping file paths to their hash values + +--- + +##### `store_file` + +`store_file(...)` + +Store a file in the storage system, using multipart upload for large files. + +**Parameters:** + +- **`file_path`**: Path to the local file +- **`target_key`**: Key/path where the file should be stored + +**Returns:** Full URI with protocol to the stored file + +--- + + diff --git a/docs/dreadnode/artifact/tree_builder.mdx b/docs/dreadnode/artifact/tree_builder.mdx new file mode 100644 index 00000000..26bd7ac8 --- /dev/null +++ b/docs/dreadnode/artifact/tree_builder.mdx @@ -0,0 +1,90 @@ +--- +title: 'tree_builder' +sidebarTitle: 'tree_builder' +groups: ["strikes"] +--- + +# Module `tree_builder` + +*(Full name: `dreadnode.artifact.tree_builder`)* + +**Source file:** `tree_builder.py` + +Tree structure builder for artifacts with directory hierarchy preservation. + +Provides efficient uploads and tree construction for frontend to consume. + +## Classes + + +### Class `ArtifactTreeBuilder` + +**Inherits from:** `object` + +Builds a hierarchical tree structure for artifacts while uploading them to storage. + +Preserves directory structure and handles efficient uploads. + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + +##### `process_artifact` + +`process_artifact(...)` + +Process an artifact (file or directory) and build its tree representation. + +**Parameters:** + +- **`local_uri`**: Path to the local file or directory + +**Returns:** Directory tree structure representing the artifact + +**Raises:** + +- `FileNotFoundError` — If the path doesn't exist + +--- + + +### Class `DirectoryNode` + +**Inherits from:** `dict` + +Represents a directory node in the artifact tree. + +Contains metadata about the directory, including its dir_path, hash, and children nodes. + + +### Class `FileNode` + +**Inherits from:** `dict` + +Represents a file node in the artifact tree. + +Contains metadata about the file, including its name, uri, size_bytes, and final_real_path. + + diff --git a/docs/dreadnode/constants.mdx b/docs/dreadnode/constants.mdx new file mode 100644 index 00000000..e9cc3632 --- /dev/null +++ b/docs/dreadnode/constants.mdx @@ -0,0 +1,12 @@ +--- +title: 'constants' +sidebarTitle: 'constants' +groups: ["strikes"] +--- + +# Module `constants` + +*(Full name: `dreadnode.constants`)* + +**Source file:** `constants.py` + diff --git a/docs/dreadnode/integrations.mdx b/docs/dreadnode/integrations.mdx new file mode 100644 index 00000000..48bc5dee --- /dev/null +++ b/docs/dreadnode/integrations.mdx @@ -0,0 +1,12 @@ +--- +title: 'integrations' +sidebarTitle: 'integrations' +groups: ["strikes"] +--- + +# Module `integrations` + +*(Full name: `dreadnode.integrations`)* + +**Source file:** `__init__.py` + diff --git a/docs/dreadnode/main.mdx b/docs/dreadnode/main.mdx new file mode 100644 index 00000000..a5a64b6c --- /dev/null +++ b/docs/dreadnode/main.mdx @@ -0,0 +1,384 @@ +--- +title: 'main' +sidebarTitle: 'main' +groups: ["strikes"] +--- + +# Module `main` + +*(Full name: `dreadnode.main`)* + +**Source file:** `main.py` + +## Classes + + +### Class `Dreadnode` + +**Inherits from:** `object` + +The core Dreadnode SDK class. + +A default instance of this class is created and can be used directly with `dreadnode.*`. + +Otherwise, you can create your own instance and configure it with `configure()`. + +#### Properties + +##### `is_default` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + +##### `api` + +`api(...)` + +Get an API client based on the current configuration or the provided server and token. + +If the server and token are not provided, the method will use the current configuration +and `configure()` needs to be called first. + +**Parameters:** + +- **`server`**: The server URL to use for the API client. +- **`token`**: The API token to use for authentication. + +**Returns:** An ApiClient instance. + +--- + +##### `configure` + +`configure(...)` + +Configure the Dreadnode SDK and call `initialize()`. + +This method should always be called before using the SDK. + +If `server` and `token` are not provided, the SDK will look in +the associated environment variables: + +- `DREADNODE_SERVER_URL` or `DREADNODE_SERVER` +- `DREADNODE_API_TOKEN` or `DREADNODE_API_KEY` + +**Parameters:** + +- **`server`**: The Dreadnode server URL. +- **`token`**: The Dreadnode API token. +- **`local_dir`**: The local directory to store data in. +- **`project`**: The defautlt project name to associate all runs with. +- **`service_name`**: The service name to use for OpenTelemetry. +- **`service_version`**: The service version to use for OpenTelemetry. +- **`console`**: Whether to log span information to the console. +- **`send_to_logfire`**: Whether to send data to Logfire. +- **`otel_scope`**: The OpenTelemetry scope name. + +--- + +##### `initialize` + +`initialize(...)` + +Initialize the Dreadnode SDK. + +This method is called automatically when you call `configure()`. + +--- + +##### `link_objects` + +`link_objects(...)` + +Associate two runtime objects with each other. + +This is useful for linking any two objects which are related to +each other, such as a model and its training data, or an input +prompt and the resulting output. + +**Parameters:** + +- **`origin`**: The origin object to link from. +- **`link`**: The linked object to link to. +- **`**attributes`**: Additional attributes to attach to the link. + +--- + +##### `log_artifact` + +`log_artifact(...)` + +Log a file or directory artifact to the current run. + +This method uploads a local file or directory to the artifact storage associated with the run. + +**Parameters:** + +- **`local_uri`**: The local path to the file to upload. +- **`to`**: The target object to log the artifact to. Only "run" is supported. + +--- + +##### `log_input` + +`log_input(...)` + +Log a single input to the current task or run. + +Inputs can be any runtime object, which are serialized, stored, and tracked +in the Dreadnode UI. + +--- + +##### `log_inputs` + +`log_inputs(...)` + +Log multiple inputs to the current task or run. + +See `log_input()` for more details. + +--- + +##### `log_metric` + +`log_metric(...)` + +--- + +##### `log_output` + +`log_output(...)` + +Log a single output to the current task or run. + +Outputs can be any runtime object, which are serialized, stored, and tracked +in the Dreadnode UI. + +--- + +##### `log_outputs` + +`log_outputs(...)` + +Log multiple outputs to the current task or run. + +See `log_output()` for more details. + +--- + +##### `log_param` + +`log_param(...)` + +Log a single parameter to the current task or run. + +Parameters are key-value pairs that are associated with the task or run +and can be used to track configuration values, hyperparameters, or other +metadata. + +**Parameters:** + +- **`key`**: The name of the parameter. +- **`value`**: The value of the parameter. +- **`to`**: The target object to log the parameter to. Can be "task-or-run" or "run". +Defaults to "task-or-run". If "task-or-run", the parameter will be logged +to the current task or run, whichever is the nearest ancestor. + +--- + +##### `log_params` + +`log_params(...)` + +Log multiple parameters to the current task or run. + +Parameters are key-value pairs that are associated with the task or run +and can be used to track configuration values, hyperparameters, or other +metadata. + +**Parameters:** + +- **`to`**: The target object to log the parameters to. Can be "task-or-run" or "run". +Defaults to "task-or-run". If "task-or-run", the parameters will be logged +to the current task or run, whichever is the nearest ancestor. +- **`**params`**: The parameters to log. Each parameter is a key-value pair. + +--- + +##### `push_update` + +`push_update(...)` + +Push any pending metric or parameter data to the server. + +This is useful for ensuring that the UI is up to date with the +latest data. Otherwise, all data for the run will be pushed +automatically when the run is closed. + +--- + +##### `run` + +`run(...)` + +Create a new run. + +Runs are the main way to track work in Dreadnode. They are +associated with a specific project and can have parameters, +inputs, and outputs logged to them. + +You cannot create runs inside other runs. + +**Parameters:** + +- **`name`**: The name of the run. If not provided, a random name will be generated. +- **`tags`**: A list of tags to attach to the run. +- **`params`**: A dictionary of parameters to attach to the run. +- **`project`**: The project name to associate the run with. If not provided, +the project passed to `configure()` will be used, or the +run will be associated with a default project. +- **`**attributes`**: Additional attributes to attach to the run span. + +--- + +##### `scorer` + +`scorer(...)` + +Make a scorer from a callable function. + +This is useful when you want to change the name of the scorer +or add additional attributes to it. + +**Parameters:** + +- **`name`**: The name of the scorer. +- **`tags`**: A list of tags to attach to the scorer. +- **`**attributes`**: A dictionary of attributes to attach to the scorer. + +**Returns:** A new Scorer object. + +--- + +##### `shutdown` + +`shutdown(...)` + +Shutdown any associate OpenTelemetry components and flush any pending spans. + +It is not required to call this method, as the SDK will automatically +flush and shutdown when the process exits. + +However, if you want to ensure that all spans are flushed before +exiting, you can call this method manually. + +--- + +##### `span` + +`span(...)` + +Create a new OpenTelemety span. + +Spans are more lightweight than tasks, but still let you track +work being performed and view it in the UI. You cannot +log parameters, inputs, or outputs to spans. + +**Parameters:** + +- **`name`**: The name of the span. +- **`tags`**: A list of tags to attach to the span. +- **`**attributes`**: A dictionary of attributes to attach to the span. + +**Returns:** A Span object. + +--- + +##### `task` + +`task(...)` + +Create a new task from a function. + +**Parameters:** + +- **`scorers`**: A list of scorers to attach to the task. These will be called after every execution +of the task and will be passed the task's output. +- **`name`**: The name of the task. +- **`label`**: The label of the task - useful for filtering in the UI. +- **`log_params`**: Whether to log all, or specific, incoming arguments to the function as parameters. +- **`log_inputs`**: Whether to log all, or specific, incoming arguments to the function as inputs. +- **`log_output`**: Whether to log the result of the function as an output. +- **`tags`**: A list of tags to attach to the task span. +- **`**attributes`**: A dictionary of attributes to attach to the task span. + +**Returns:** A new Task object. + +--- + +##### `task_span` + +`task_span(...)` + +Create a task span without an explicit associated function. + +This is useful for creating tasks on the fly without having to +define a function. + +**Parameters:** + +- **`name`**: The name of the task. +- **`label`**: The label of the task - useful for filtering in the UI. +- **`params`**: A dictionary of parameters to attach to the task span. +- **`tags`**: A list of tags to attach to the task span. +- **`**attributes`**: A dictionary of attributes to attach to the task span. + +**Returns:** A TaskSpan object. + +--- + + +### Class `DreadnodeConfigWarning` + +**Inherits from:** `UserWarning` + +Base class for warnings generated by user code. + + +### Class `DreadnodeUsageWarning` + +**Inherits from:** `UserWarning` + +Base class for warnings generated by user code. + + diff --git a/docs/dreadnode/metric.mdx b/docs/dreadnode/metric.mdx new file mode 100644 index 00000000..f3bcffe2 --- /dev/null +++ b/docs/dreadnode/metric.mdx @@ -0,0 +1,137 @@ +--- +title: 'metric' +sidebarTitle: 'metric' +groups: ["strikes"] +--- + +# Module `metric` + +*(Full name: `dreadnode.metric`)* + +**Source file:** `metric.py` + +## Classes + + +### Class `Metric` + +**Inherits from:** `object` + +Any reported value regarding the state of a run, task, and optionally object (input/output). + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + +##### `apply_mode` + +`apply_mode(...)` + +Apply an aggregation mode to the metric. + +This will modify the metric in place. + +**Parameters:** + +- **`mode`**: The mode to apply. One of "sum", "min", "max", or "inc". +- **`others`**: A list of other metrics to apply the mode to. + +**Returns:** self + +--- + + +### Class `MetricWarning` + +**Inherits from:** `UserWarning` + +Base class for warnings generated by user code. + + +### Class `Scorer` + +**Inherits from:** `typing.Generic` + +Scorer(tracer: opentelemetry.trace.Tracer, name: str, tags: Sequence[str], attributes: dict[str, typing.Any], func: Union[Callable[[~T], Awaitable[float | int | bool | dreadnode.metric.Metric]], Callable[[~T], float | int | bool | dreadnode.metric.Metric]], step: int = 0, auto_increment_step: bool = False) + +#### Methods + +##### `__call__` + +`__call__(...)` + +Execute the scorer and return the metric. + +Any output value will be converted to a Metric object. + +**Parameters:** + +- **`object`**: The object to score. + +**Returns:** A Metric object. + +--- + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__post_init__` + +`__post_init__(...)` + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + +##### `clone` + +`clone(...)` + +Clone the scorer. + +**Returns:** A new Scorer. + +--- + + diff --git a/docs/dreadnode/object.mdx b/docs/dreadnode/object.mdx new file mode 100644 index 00000000..64d691d0 --- /dev/null +++ b/docs/dreadnode/object.mdx @@ -0,0 +1,114 @@ +--- +title: 'object' +sidebarTitle: 'object' +groups: ["strikes"] +--- + +# Module `object` + +*(Full name: `dreadnode.object`)* + +**Source file:** `object.py` + +## Classes + + +### Class `ObjectRef` + +**Inherits from:** `object` + +ObjectRef(name: str, label: str, hash: str) + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + + +### Class `ObjectUri` + +**Inherits from:** `object` + +ObjectUri(hash: str, schema_hash: str, uri: str, size: int, type: Literal['uri'] = 'uri') + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + + +### Class `ObjectVal` + +**Inherits from:** `object` + +ObjectVal(hash: str, schema_hash: str, value: Any, type: Literal['val'] = 'val') + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + + diff --git a/docs/dreadnode/serialization.mdx b/docs/dreadnode/serialization.mdx new file mode 100644 index 00000000..128f11a3 --- /dev/null +++ b/docs/dreadnode/serialization.mdx @@ -0,0 +1,68 @@ +--- +title: 'serialization' +sidebarTitle: 'serialization' +groups: ["strikes"] +--- + +# Module `serialization` + +*(Full name: `dreadnode.serialization`)* + +**Source file:** `serialization.py` + +## Classes + + +### Class `Serialized` + +**Inherits from:** `object` + +Serialized(data: Union[int, float, str, bool, NoneType, list['JsonValue'], tuple['JsonValue', ...], ForwardRef('JsonDict')], data_bytes: bytes | None, data_len: int, data_hash: str, schema: dict[str, typing.Union[int, float, str, bool, NoneType, list['JsonValue'], tuple['JsonValue', ...], ForwardRef('JsonDict')]], schema_hash: str) + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + + +## Functions + +### `serialize` + +```python +serialize(obj: Any) -> dreadnode.serialization.Serialized +``` + +Serializes a Python object into a JSON-compatible structure and + +generates a corresponding JSON Schema, ensuring consistency between +the serialization format and the schema. + +**Parameters:** + +- **`obj`**: The Python object to process. + +**Returns:** An object containing the serialized data, schema, and their hashes. + + diff --git a/docs/dreadnode/task.mdx b/docs/dreadnode/task.mdx new file mode 100644 index 00000000..6c61e113 --- /dev/null +++ b/docs/dreadnode/task.mdx @@ -0,0 +1,308 @@ +--- +title: 'task' +sidebarTitle: 'task' +groups: ["strikes"] +--- + +# Module `task` + +*(Full name: `dreadnode.task`)* + +**Source file:** `task.py` + +## Classes + + +### Class `Task` + +**Inherits from:** `typing.Generic` + +Structured task wrapper for a function that can be executed within a run. + +Tasks allow you to associate metadata, inputs, outputs, and metrics for a unit of work. + +#### Methods + +##### `__call__` + +`__call__(...)` + +Call self as a function. + +--- + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__get__` + +`__get__(...)` + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__post_init__` + +`__post_init__(...)` + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + +##### `clone` + +`clone(...)` + +Clone a task. + +**Returns:** A new Task instance with the same attributes as this one. + +--- + +##### `map` + +`map(...)` + +Run the task multiple times and return a list of outputs. + +**Parameters:** + +- **`count`**: The number of times to run the task. +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** A list of outputs from each task execution. + +--- + +##### `map_run` + +`map_run(...)` + +Run the task multiple times and return a list of spans. + +**Parameters:** + +- **`count`**: The number of times to run the task. +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** A TaskSpanList associated with each task execution. + +--- + +##### `run` + +`run(...)` + +Execute the task and return the result as a TaskSpan. + +**Parameters:** + +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** The span associated with task execution. + +--- + +##### `top_n` + +`top_n(...)` + +Run the task multiple times and return the top n outputs. + +**Parameters:** + +- **`count`**: The number of times to run the task. +- **`n`**: The number of top outputs to return. +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** A list of the top n outputs from the task executions. + +--- + +##### `try_` + +`try_(...)` + +Attempt to run the task and return the result. + +If the task fails, a warning is logged and None is returned. + +**Parameters:** + +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** The output of the task, or None if the task failed. + +--- + +##### `try_map` + +`try_map(...)` + +Attempt to run the task multiple times and return a list of outputs. + +If any task fails, a warning is logged and None is returned for that task. + +**Parameters:** + +- **`count`**: The number of times to run the task. +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** A list of outputs from each task execution. + +--- + +##### `try_map_run` + +`try_map_run(...)` + +Attempt to run the task multiple times and return a list of spans. + +If any task fails, a warning is logged and None is returned for that task. + +**Parameters:** + +- **`count`**: The number of times to run the task. +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** A TaskSpanList associated with each task execution. + +--- + +##### `try_run` + +`try_run(...)` + +Attempt to run the task and return the result as a TaskSpan. + +If the task fails, a warning is logged and None is returned. + +**Parameters:** + +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** The span associated with task execution, or None if the task failed. + +--- + +##### `try_top_n` + +`try_top_n(...)` + +Attempt to run the task multiple times and return the top n outputs. + +If any task fails, a warning is logged and None is returned for that task. + +**Parameters:** + +- **`count`**: The number of times to run the task. +- **`n`**: The number of top outputs to return. +- **`args`**: The arguments to pass to the task. +- **`kwargs`**: The keyword arguments to pass to the task. + +**Returns:** A list of the top n outputs from the task executions. + +--- + +##### `with_` + +`with_(...)` + +Clone a task and modify its attributes. + +**Parameters:** + +- **`scorers`**: A list of new scorers to set or append to the task. +- **`name`**: The new name for the task. +- **`tags`**: A list of new tags to set or append to the task. +- **`label`**: The new label for the task. +- **`log_params`**: Whether to log all, or specific, incoming arguments to the function as parameters. +- **`log_inputs`**: Whether to log all, or specific, incoming arguments to the function as inputs. +- **`log_output`**: Whether to automatically log the result of the function as an output. +- **`append`**: If True, appends the new scorers and tags to the existing ones. If False, replaces them. +- **`**attributes`**: Additional attributes to set or update in the task. + +**Returns:** A new Task instance with the modified attributes. + +--- + + +### Class `TaskFailedWarning` + +**Inherits from:** `UserWarning` + +Base class for warnings generated by user code. + + +### Class `TaskGeneratorWarning` + +**Inherits from:** `UserWarning` + +Base class for warnings generated by user code. + + +### Class `TaskSpanList` + +**Inherits from:** `list` + +Lightweight wrapper around a list of TaskSpans to provide some convenience methods. + +#### Methods + +##### `sorted` + +`sorted(...)` + +Sorts the spans in this list by their average metric value. + +**Parameters:** + +- **`reverse`**: If True, sorts in descending order. Defaults to True. Default: `True` + +**Returns:** A new TaskSpanList sorted by average metric value. + +--- + +##### `top_n` + +`top_n(...)` + +Take the top n spans from this list, sorted by their average metric value. + +**Parameters:** + +- **`n`**: The number of spans to take. +- **`as_outputs`**: If True, returns a list of outputs instead of spans. Defaults to False. Default: `False` +- **`reverse`**: If True, sorts in descending order. Defaults to True. Default: `True` + +**Returns:** A new TaskSpanList or list of outputs sorted by average metric value. + +--- + + diff --git a/docs/dreadnode/tracing.mdx b/docs/dreadnode/tracing.mdx new file mode 100644 index 00000000..c9b50ccd --- /dev/null +++ b/docs/dreadnode/tracing.mdx @@ -0,0 +1,12 @@ +--- +title: 'tracing' +sidebarTitle: 'tracing' +groups: ["strikes"] +--- + +# Module `tracing` + +*(Full name: `dreadnode.tracing`)* + +**Source file:** `__init__.py` + diff --git a/docs/dreadnode/tracing/constants.mdx b/docs/dreadnode/tracing/constants.mdx new file mode 100644 index 00000000..63360662 --- /dev/null +++ b/docs/dreadnode/tracing/constants.mdx @@ -0,0 +1,12 @@ +--- +title: 'constants' +sidebarTitle: 'constants' +groups: ["strikes"] +--- + +# Module `constants` + +*(Full name: `dreadnode.tracing.constants`)* + +**Source file:** `constants.py` + diff --git a/docs/dreadnode/tracing/exporters.mdx b/docs/dreadnode/tracing/exporters.mdx new file mode 100644 index 00000000..ceecc662 --- /dev/null +++ b/docs/dreadnode/tracing/exporters.mdx @@ -0,0 +1,219 @@ +--- +title: 'exporters' +sidebarTitle: 'exporters' +groups: ["strikes"] +--- + +# Module `exporters` + +*(Full name: `dreadnode.tracing.exporters`)* + +**Source file:** `exporters.py` + +## Classes + + +### Class `FileExportConfig` + +**Inherits from:** `object` + +Configuration for signal exports to JSONL files. + +#### Methods + +##### `__eq__` + +`__eq__(...)` + +Return self==value. + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `__repr__` + +`__repr__(...)` + +Return repr(self). + +--- + +##### `get_path` + +`get_path(...)` + +Get the file path for a specific signal type. + +--- + + +### Class `FileLogExporter` + +**Inherits from:** `opentelemetry.sdk._logs._internal.export.LogExporter` + +LogExporter that writes logs to a file in OTLP format. + +#### Properties + +##### `file` + +**Type:** `IO[str]` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `export` + +`export(...)` + +Exports a batch of logs. + +**Parameters:** + +- **`batch`**: The list of `LogData` objects to be exported + +**Returns:** The result of the export + +--- + +##### `force_flush` + +`force_flush(...)` + +--- + +##### `shutdown` + +`shutdown(...)` + +Shuts down the exporter. + +Called when the SDK is shut down. + +--- + + +### Class `FileMetricReader` + +**Inherits from:** `opentelemetry.sdk.metrics._internal.export.MetricReader` + +MetricReader that writes metrics to a file in OTLP format. + +#### Properties + +##### `file` + +**Type:** `IO[str]` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `shutdown` + +`shutdown(...)` + +Shuts down the MetricReader. This method provides a way + +for the MetricReader to do any cleanup required. A metric reader can +only be shutdown once, any subsequent calls are ignored and return +failure status. + +When a `MetricReader` is registered on a +:class:`~opentelemetry.sdk.metrics.MeterProvider`, +:meth:`~opentelemetry.sdk.metrics.MeterProvider.shutdown` will invoke this +automatically. + +--- + + +### Class `FileSpanExporter` + +**Inherits from:** `opentelemetry.sdk.trace.export.SpanExporter` + +SpanExporter that writes spans to a file in OTLP format. + +#### Properties + +##### `file` + +**Type:** `IO[str]` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `export` + +`export(...)` + +Exports a batch of telemetry data. + +**Parameters:** + +- **`spans`**: The list of `opentelemetry.trace.Span` objects to be exported + +**Returns:** The result of the export + +--- + +##### `force_flush` + +`force_flush(...)` + +Hint to ensure that the export of any spans the exporter has received + +prior to the call to ForceFlush SHOULD be completed as soon as possible, preferably +before returning from this method. + +--- + +##### `shutdown` + +`shutdown(...)` + +Shuts down the exporter. + +Called when the SDK is shut down. + +--- + + diff --git a/docs/dreadnode/tracing/span.mdx b/docs/dreadnode/tracing/span.mdx new file mode 100644 index 00000000..197eff66 --- /dev/null +++ b/docs/dreadnode/tracing/span.mdx @@ -0,0 +1,652 @@ +--- +title: 'span' +sidebarTitle: 'span' +groups: ["strikes"] +--- + +# Module `span` + +*(Full name: `dreadnode.tracing.span`)* + +**Source file:** `span.py` + +## Classes + + +### Class `RunSpan` + +**Inherits from:** `dreadnode.tracing.span.Span` + +Provides read-only access to span attributes. + +Users should NOT be creating these objects directly. `ReadableSpan`s are created as +a direct result from using the tracing pipeline via the `Tracer`. + +#### Properties + +##### `inputs` + +**Type:** `dict[str, Any]` *(property)* + +*Has: getter* + +--- + +##### `is_recording` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `metrics` + +**Type:** `dict[str, list[dreadnode.metric.Metric]]` *(property)* + +*Has: getter* + +--- + +##### `outputs` + +**Type:** `dict[str, Any]` *(property)* + +*Has: getter* + +--- + +##### `params` + +**Type:** `dict[str, Any]` *(property)* + +*Has: getter* + +--- + +##### `run_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `span_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `tags` + +**Type:** `tuple[str, ...]` *(property)* + +*Has: getter, setter* + +--- + +##### `trace_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__enter__` + +`__enter__(...)` + +--- + +##### `__exit__` + +`__exit__(...)` + +--- + +##### `__getattr__` + +`__getattr__(...)` + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `get_attribute` + +`get_attribute(...)` + +--- + +##### `get_attributes` + +`get_attributes(...)` + +--- + +##### `get_object` + +`get_object(...)` + +--- + +##### `link_objects` + +`link_objects(...)` + +--- + +##### `log_artifact` + +`log_artifact(...)` + +Logs a local file or directory as an artifact to the object store. + +Preserves directory structure and uses content hashing for deduplication. + +**Parameters:** + +- **`local_uri`**: Path to the local file or directory + +**Returns:** DirectoryNode representing the artifact's tree structure + +**Raises:** + +- `FileNotFoundError` — If the path doesn't exist + +--- + +##### `log_event` + +`log_event(...)` + +--- + +##### `log_input` + +`log_input(...)` + +--- + +##### `log_metric` + +`log_metric(...)` + +--- + +##### `log_object` + +`log_object(...)` + +--- + +##### `log_output` + +`log_output(...)` + +--- + +##### `log_param` + +`log_param(...)` + +--- + +##### `log_params` + +`log_params(...)` + +--- + +##### `push_update` + +`push_update(...)` + +--- + +##### `set_attribute` + +`set_attribute(...)` + +--- + +##### `set_attributes` + +`set_attributes(...)` + +--- + + +### Class `RunUpdateSpan` + +**Inherits from:** `dreadnode.tracing.span.Span` + +Provides read-only access to span attributes. + +Users should NOT be creating these objects directly. `ReadableSpan`s are created as +a direct result from using the tracing pipeline via the `Tracer`. + +#### Properties + +##### `is_recording` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `span_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `tags` + +**Type:** `tuple[str, ...]` *(property)* + +*Has: getter, setter* + +--- + +##### `trace_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__enter__` + +`__enter__(...)` + +--- + +##### `__exit__` + +`__exit__(...)` + +--- + +##### `__getattr__` + +`__getattr__(...)` + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `get_attribute` + +`get_attribute(...)` + +--- + +##### `get_attributes` + +`get_attributes(...)` + +--- + +##### `log_event` + +`log_event(...)` + +--- + +##### `set_attribute` + +`set_attribute(...)` + +--- + +##### `set_attributes` + +`set_attributes(...)` + +--- + + +### Class `Span` + +**Inherits from:** `opentelemetry.sdk.trace.ReadableSpan` + +Provides read-only access to span attributes. + +Users should NOT be creating these objects directly. `ReadableSpan`s are created as +a direct result from using the tracing pipeline via the `Tracer`. + +#### Properties + +##### `is_recording` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `span_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `tags` + +**Type:** `tuple[str, ...]` *(property)* + +*Has: getter, setter* + +--- + +##### `trace_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__enter__` + +`__enter__(...)` + +--- + +##### `__exit__` + +`__exit__(...)` + +--- + +##### `__getattr__` + +`__getattr__(...)` + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `get_attribute` + +`get_attribute(...)` + +--- + +##### `get_attributes` + +`get_attributes(...)` + +--- + +##### `log_event` + +`log_event(...)` + +--- + +##### `set_attribute` + +`set_attribute(...)` + +--- + +##### `set_attributes` + +`set_attributes(...)` + +--- + + +### Class `TaskSpan` + +**Inherits from:** `dreadnode.tracing.span.Span`, `typing.Generic` + +Provides read-only access to span attributes. + +Users should NOT be creating these objects directly. `ReadableSpan`s are created as +a direct result from using the tracing pipeline via the `Tracer`. + +#### Properties + +##### `inputs` + +**Type:** `dict[str, Any]` *(property)* + +*Has: getter* + +--- + +##### `is_recording` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `metrics` + +**Type:** `dict[str, list[dreadnode.metric.Metric]]` *(property)* + +*Has: getter* + +--- + +##### `output` + +**Type:** `~R` *(property)* + +*Has: getter, setter* + +--- + +##### `outputs` + +**Type:** `dict[str, Any]` *(property)* + +*Has: getter* + +--- + +##### `params` + +**Type:** `dict[str, Any]` *(property)* + +*Has: getter* + +--- + +##### `parent_task_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `run` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `run_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `span_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +##### `tags` + +**Type:** `tuple[str, ...]` *(property)* + +*Has: getter, setter* + +--- + +##### `trace_id` + +**Type:** `\` *(property)* + +*Has: getter* + +--- + +#### Methods + +##### `__enter__` + +`__enter__(...)` + +--- + +##### `__exit__` + +`__exit__(...)` + +--- + +##### `__getattr__` + +`__getattr__(...)` + +--- + +##### `__init__` + +`__init__(...)` + +Initialize self. See help(type(self)) for accurate signature. + +--- + +##### `get_attribute` + +`get_attribute(...)` + +--- + +##### `get_attributes` + +`get_attributes(...)` + +--- + +##### `get_average_metric_value` + +`get_average_metric_value(...)` + +--- + +##### `log_event` + +`log_event(...)` + +--- + +##### `log_input` + +`log_input(...)` + +--- + +##### `log_metric` + +`log_metric(...)` + +--- + +##### `log_output` + +`log_output(...)` + +--- + +##### `log_param` + +`log_param(...)` + +--- + +##### `log_params` + +`log_params(...)` + +--- + +##### `set_attribute` + +`set_attribute(...)` + +--- + +##### `set_attributes` + +`set_attributes(...)` + +--- + + +## Functions + +### `prepare_otlp_attribute` + +```python +prepare_otlp_attribute(value: Any) -> Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]] +``` + +### `prepare_otlp_attributes` + +```python +prepare_otlp_attributes(attributes: dict[str, typing.Any]) -> dict[str, typing.Union[str, bool, int, float, typing.Sequence[str], typing.Sequence[bool], typing.Sequence[int], typing.Sequence[float]]] +``` + + diff --git a/docs/dreadnode/types.mdx b/docs/dreadnode/types.mdx new file mode 100644 index 00000000..04fc7611 --- /dev/null +++ b/docs/dreadnode/types.mdx @@ -0,0 +1,28 @@ +--- +title: 'types' +sidebarTitle: 'types' +groups: ["strikes"] +--- + +# Module `types` + +*(Full name: `dreadnode.types`)* + +**Source file:** `types.py` + +## Classes + + +### Class `Unset` + +**Inherits from:** `object` + +#### Methods + +##### `__bool__` + +`__bool__(...)` + +--- + + diff --git a/docs/dreadnode/util.mdx b/docs/dreadnode/util.mdx new file mode 100644 index 00000000..26a5aec8 --- /dev/null +++ b/docs/dreadnode/util.mdx @@ -0,0 +1,35 @@ +--- +title: 'util' +sidebarTitle: 'util' +groups: ["strikes"] +--- + +# Module `util` + +*(Full name: `dreadnode.util`)* + +**Source file:** `util.py` + +## Functions + +### `handle_internal_errors` + +```python +handle_internal_errors() -> Iterator[NoneType] +``` + +### `log_internal_error` + +```python +log_internal_error() -> None +``` + +### `safe_repr` + +```python +safe_repr(obj: Any) -> str +``` + +Return some kind of non-empty string representation of an object, catching exceptions. + + diff --git a/docs/dreadnode/version.mdx b/docs/dreadnode/version.mdx new file mode 100644 index 00000000..bbee8125 --- /dev/null +++ b/docs/dreadnode/version.mdx @@ -0,0 +1,12 @@ +--- +title: 'version' +sidebarTitle: 'version' +groups: ["strikes"] +--- + +# Module `version` + +*(Full name: `dreadnode.version`)* + +**Source file:** `version.py` + From e747eb6ce208df0b357f28147c88d74575dd89ce Mon Sep 17 00:00:00 2001 From: Brian Greunke Date: Fri, 9 May 2025 10:36:28 -0500 Subject: [PATCH 2/4] docs: regenerated docstrings for everything --- dreadnode/__init__.py | 47 +++ dreadnode/api/__init__.py | 10 + dreadnode/api/client.py | 181 ++++++++++- dreadnode/api/models.py | 214 ++++++++++++- dreadnode/artifact/__init__.py | 15 + dreadnode/constants.py | 21 ++ dreadnode/integrations/__init__.py | 16 + dreadnode/integrations/transformers.py | 115 ++++++- dreadnode/main.py | 218 +++++++------ dreadnode/metric.py | 98 +++--- dreadnode/tracing/__init__.py | 16 + dreadnode/tracing/constants.py | 8 + dreadnode/tracing/exporters.py | 132 +++++++- dreadnode/tracing/span.py | 405 ++++++++++++++++++++++++- dreadnode/util.py | 43 ++- 15 files changed, 1371 insertions(+), 168 deletions(-) diff --git a/dreadnode/__init__.py b/dreadnode/__init__.py index a7bbd9cd..900e6d0c 100644 --- a/dreadnode/__init__.py +++ b/dreadnode/__init__.py @@ -1,3 +1,50 @@ +"""Dreadnode SDK. + +This module serves as the main entry point for the Dreadnode SDK. It provides +core functionality for configuring, managing tasks, logging metrics, and +handling spans for tracing operations. The SDK is designed to facilitate +interaction with the Dreadnode platform. + +Attributes: + configure (function): Configures the Dreadnode instance. + shutdown (function): Shuts down the Dreadnode instance. + api (object): Provides access to the API interface of the Dreadnode instance. + span (object): Manages tracing spans. + task (object): Handles task-related operations. + task_span (object): Manages task-specific spans. + run (object): Represents the current run context. + scorer (object): Provides scoring functionality. + push_update (function): Pushes updates to the Dreadnode instance. + log_metric (function): Logs a metric to the Dreadnode instance. + log_param (function): Logs a single parameter to the Dreadnode instance. + log_params (function): Logs multiple parameters to the Dreadnode instance. + log_input (function): Logs a single input to the Dreadnode instance. + log_inputs (function): Logs multiple inputs to the Dreadnode instance. + log_output (function): Logs an output to the Dreadnode instance. + link_objects (function): Links objects in the Dreadnode instance. + log_artifact (function): Logs an artifact to the Dreadnode instance. + __version__ (str): The version of the Dreadnode SDK. + +Classes: + Dreadnode: The main class for interacting with the Dreadnode platform. + Metric: Represents a metric in the Dreadnode SDK. + MetricDict: A dictionary-like structure for managing metrics. + Scorer: Provides scoring capabilities. + Object: Represents an object in the Dreadnode SDK. + Task: Represents a task in the Dreadnode SDK. + Span: Represents a tracing span. + RunSpan: Represents a span for a run. + TaskSpan: Represents a span for a task. + +Example: + Import the module and use its functionality as follows: + + from dreadnode import configure, log_metric + + configure(api_key="your_api_key") + log_metric(name="example_metric", value=42) +""" + from dreadnode.main import DEFAULT_INSTANCE, Dreadnode from dreadnode.metric import Metric, MetricDict, Scorer from dreadnode.object import Object diff --git a/dreadnode/api/__init__.py b/dreadnode/api/__init__.py index e69de29b..8493cc92 100644 --- a/dreadnode/api/__init__.py +++ b/dreadnode/api/__init__.py @@ -0,0 +1,10 @@ +""" +This module initializes the `dreadnode.api` package. + +The `dreadnode.api` package provides the API layer for interacting with the +Dreadnode SDK. It includes modules and functions for handling requests, +responses, and other API-related functionality. + +Modules in this package should be imported and used to facilitate communication +with external services or internal components of the Dreadnode system. +""" diff --git a/dreadnode/api/client.py b/dreadnode/api/client.py index 1f512c4c..2e8e6af8 100644 --- a/dreadnode/api/client.py +++ b/dreadnode/api/client.py @@ -1,3 +1,17 @@ +""" +This module provides the `ApiClient` class, which serves as a client for interacting +with the Dreadnode API. It includes methods for managing projects, runs, tasks, and +exporting data in various formats. + +Dependencies: + - httpx + - pandas + - pydantic + - ulid + - dreadnode.util.logger + - dreadnode.version.VERSION +""" + import io import json import typing as t @@ -26,7 +40,15 @@ class ApiClient: - """Client for the Dreadnode API.""" + """Client for the Dreadnode API. + + This class provides methods to interact with the Dreadnode API, including + managing projects, runs, tasks, and exporting data. + + Attributes: + _base_url (str): The base URL of the API. + _client (httpx.Client): The HTTP client used for making requests. + """ def __init__( self, @@ -35,6 +57,13 @@ def __init__( *, debug: bool = False, ): + """Initializes the ApiClient. + + Args: + base_url (str): The base URL of the API. + api_key (str): The API key for authentication. + debug (bool, optional): Whether to enable debug logging. Defaults to False. + """ self._base_url = base_url.rstrip("/") if not self._base_url.endswith("/api"): self._base_url += "/api" @@ -54,8 +83,11 @@ def __init__( self._client.event_hooks["response"].append(self._log_response) def _log_request(self, request: httpx.Request) -> None: - """Log every request to the console if debug is enabled.""" + """Logs HTTP requests if debug is enabled. + Args: + request (httpx.Request): The HTTP request object. + """ logger.debug("-------------------------------------------") logger.debug("%s %s", request.method, request.url) logger.debug("Headers: %s", request.headers) @@ -63,8 +95,11 @@ def _log_request(self, request: httpx.Request) -> None: logger.debug("-------------------------------------------") def _log_response(self, response: httpx.Response) -> None: - """Log every response to the console if debug is enabled.""" + """Logs HTTP responses if debug is enabled. + Args: + response (httpx.Response): The HTTP response object. + """ logger.debug("-------------------------------------------") logger.debug("Response: %s", response.status_code) logger.debug("Headers: %s", response.headers) @@ -72,12 +107,18 @@ def _log_response(self, response: httpx.Response) -> None: logger.debug("--------------------------------------------") def _get_error_message(self, response: httpx.Response) -> str: - """Get the error message from the response.""" + """Extracts the error message from an HTTP response. + + Args: + response (httpx.Response): The HTTP response object. + Returns: + str: The error message. + """ try: obj = response.json() return f"{response.status_code}: {obj.get('detail', json.dumps(obj))}" - except Exception: # noqa: BLE001 + except Exception: return str(response.content) def _request( @@ -87,8 +128,17 @@ def _request( params: dict[str, t.Any] | None = None, json_data: dict[str, t.Any] | None = None, ) -> httpx.Response: - """Make a raw request to the API.""" + """Makes a raw HTTP request to the API. + + Args: + method (str): The HTTP method (e.g., "GET", "POST"). + path (str): The API endpoint path. + params (dict[str, t.Any], optional): Query parameters. Defaults to None. + json_data (dict[str, t.Any], optional): JSON payload. Defaults to None. + Returns: + httpx.Response: The HTTP response object. + """ return self._client.request(method, path, json=json_data, params=params) def request( @@ -98,10 +148,22 @@ def request( params: dict[str, t.Any] | None = None, json_data: dict[str, t.Any] | None = None, ) -> httpx.Response: - """Make a request to the API. Raise an exception for non-200 status codes.""" + """Makes an HTTP request to the API and raises exceptions for errors. + Args: + method (str): The HTTP method (e.g., "GET", "POST"). + path (str): The API endpoint path. + params (dict[str, t.Any], optional): Query parameters. Defaults to None. + json_data (dict[str, t.Any], optional): JSON payload. Defaults to None. + + Returns: + httpx.Response: The HTTP response object. + + Raises: + RuntimeError: If the response status code indicates an error. + """ response = self._request(method, path, params, json_data) - if response.status_code == 401: # noqa: PLR2004 + if response.status_code == 401: raise RuntimeError("Authentication failed, please check your API token.") try: @@ -112,26 +174,71 @@ def request( return response def list_projects(self) -> list[Project]: + """Lists all projects. + + Returns: + list[Project]: A list of Project objects. + """ response = self.request("GET", "/strikes/projects") return [Project(**project) for project in response.json()] def get_project(self, project: str) -> Project: + """Retrieves details of a specific project. + + Args: + project (str): The project identifier. + + Returns: + Project: The Project object. + """ response = self.request("GET", f"/strikes/projects/{project!s}") return Project(**response.json()) def list_runs(self, project: str) -> list[Run]: + """Lists all runs for a specific project. + + Args: + project (str): The project identifier. + + Returns: + list[Run]: A list of Run objects. + """ response = self.request("GET", f"/strikes/projects/{project!s}/runs") return [Run(**run) for run in response.json()] def get_run(self, run: str | ULID) -> Run: + """Retrieves details of a specific run. + + Args: + run (str | ULID): The run identifier. + + Returns: + Run: The Run object. + """ response = self.request("GET", f"/strikes/projects/runs/{run!s}") return Run(**response.json()) def get_run_tasks(self, run: str | ULID) -> list[Task]: + """Lists all tasks for a specific run. + + Args: + run (str | ULID): The run identifier. + + Returns: + list[Task]: A list of Task objects. + """ response = self.request("GET", f"/strikes/projects/runs/{run!s}/tasks") return [Task(**task) for task in response.json()] def get_run_trace(self, run: str | ULID) -> list[Task | TraceSpan]: + """Retrieves the trace spans for a specific run. + + Args: + run (str | ULID): The run identifier. + + Returns: + list[Task | TraceSpan]: A list of Task or TraceSpan objects. + """ response = self.request("GET", f"/strikes/projects/runs/{run!s}/spans") spans: list[Task | TraceSpan] = [] for item in response.json(): @@ -148,10 +255,20 @@ def export_runs( project: str, *, filter: str | None = None, - # format: ExportFormat = "parquet", status: StatusFilter = "completed", aggregations: list[MetricAggregationType] | None = None, ) -> pd.DataFrame: + """Exports run data for a specific project. + + Args: + project (str): The project identifier. + filter (str, optional): A filter string. Defaults to None. + status (StatusFilter, optional): The status filter. Defaults to "completed". + aggregations (list[MetricAggregationType], optional): Aggregations to apply. Defaults to None. + + Returns: + pd.DataFrame: A DataFrame containing the exported data. + """ response = self.request( "GET", f"/strikes/projects/{project!s}/export", @@ -169,11 +286,22 @@ def export_metrics( project: str, *, filter: str | None = None, - # format: ExportFormat = "parquet", status: StatusFilter = "completed", metrics: list[str] | None = None, aggregations: list[MetricAggregationType] | None = None, ) -> pd.DataFrame: + """Exports metric data for a specific project. + + Args: + project (str): The project identifier. + filter (str, optional): A filter string. Defaults to None. + status (StatusFilter, optional): The status filter. Defaults to "completed". + metrics (list[str], optional): A list of metrics to include. Defaults to None. + aggregations (list[MetricAggregationType], optional): Aggregations to apply. Defaults to None. + + Returns: + pd.DataFrame: A DataFrame containing the exported data. + """ response = self.request( "GET", f"/strikes/projects/{project!s}/export/metrics", @@ -192,12 +320,24 @@ def export_parameters( project: str, *, filter: str | None = None, - # format: ExportFormat = "parquet", status: StatusFilter = "completed", parameters: list[str] | None = None, metrics: list[str] | None = None, aggregations: list[MetricAggregationType] | None = None, ) -> pd.DataFrame: + """Exports parameter data for a specific project. + + Args: + project (str): The project identifier. + filter (str, optional): A filter string. Defaults to None. + status (StatusFilter, optional): The status filter. Defaults to "completed". + parameters (list[str], optional): A list of parameters to include. Defaults to None. + metrics (list[str], optional): A list of metrics to include. Defaults to None. + aggregations (list[MetricAggregationType], optional): Aggregations to apply. Defaults to None. + + Returns: + pd.DataFrame: A DataFrame containing the exported data. + """ response = self.request( "GET", f"/strikes/projects/{project!s}/export/parameters", @@ -217,12 +357,24 @@ def export_timeseries( project: str, *, filter: str | None = None, - # format: ExportFormat = "parquet", status: StatusFilter = "completed", metrics: list[str] | None = None, time_axis: TimeAxisType = "relative", aggregations: list[TimeAggregationType] | None = None, ) -> pd.DataFrame: + """Exports timeseries data for a specific project. + + Args: + project (str): The project identifier. + filter (str, optional): A filter string. Defaults to None. + status (StatusFilter, optional): The status filter. Defaults to "completed". + metrics (list[str], optional): A list of metrics to include. Defaults to None. + time_axis (TimeAxisType, optional): The time axis type. Defaults to "relative". + aggregations (list[TimeAggregationType], optional): Aggregations to apply. Defaults to None. + + Returns: + pd.DataFrame: A DataFrame containing the exported data. + """ response = self.request( "GET", f"/strikes/projects/{project!s}/export/timeseries", @@ -240,5 +392,10 @@ def export_timeseries( # User data access def get_user_data_credentials(self) -> UserDataCredentials: + """Retrieves user data credentials. + + Returns: + UserDataCredentials: The user data credentials. + """ response = self.request("GET", "/user-data/credentials") return UserDataCredentials(**response.json()) diff --git a/dreadnode/api/models.py b/dreadnode/api/models.py index 0c11913a..51c8f3dc 100644 --- a/dreadnode/api/models.py +++ b/dreadnode/api/models.py @@ -1,3 +1,12 @@ +""" +This module defines the data models used in the Dreadnode API. + +The models are implemented using Pydantic's `BaseModel` and include various +types for representing tasks, spans, metrics, objects, and user-related data. +These models are used for serialization, validation, and type enforcement +throughout the API. +""" + import typing as t from datetime import datetime from uuid import UUID @@ -7,26 +16,33 @@ AnyDict = dict[str, t.Any] -# User - class UserAPIKey(BaseModel): + """Represents a user's API key.""" + key: str class UserResponse(BaseModel): + """Represents a response containing user information. + + Attributes: + id (UUID): The unique identifier for the user. + email_address (str): The user's email address. + username (str): The user's username. + api_key (UserAPIKey): The user's API key. + """ + id: UUID email_address: str username: str api_key: UserAPIKey -# Strikes - SpanStatus = t.Literal[ "pending", # A pending span has been created "completed", # The span has been finished - "failed", # The raised an exception + "failed", # The span raised an exception ] ExportFormat = t.Literal["csv", "json", "jsonl", "parquet"] @@ -48,24 +64,61 @@ class UserResponse(BaseModel): class SpanException(BaseModel): + """Represents an exception that occurred during a span. + + Attributes: + type (str): The type of the exception. + message (str): The exception message. + stacktrace (str): The stack trace of the exception. + """ + type: str message: str stacktrace: str class SpanEvent(BaseModel): + """Represents an event within a span. + + Attributes: + timestamp (datetime): The timestamp of the event. + name (str): The name of the event. + attributes (AnyDict): Additional attributes associated with the event. + """ + timestamp: datetime name: str attributes: AnyDict class SpanLink(BaseModel): + """Represents a link between spans. + + Attributes: + trace_id (str): The trace ID of the linked span. + span_id (str): The span ID of the linked span. + attributes (AnyDict): Additional attributes associated with the link. + """ + trace_id: str span_id: str attributes: AnyDict class TraceLog(BaseModel): + """Represents a log entry within a trace. + + Attributes: + timestamp (datetime): The timestamp of the log entry. + body (str): The log message body. + severity (str): The severity level of the log. + service (str | None): The service associated with the log. + trace_id (str | None): The trace ID associated with the log. + span_id (str | None): The span ID associated with the log. + attributes (AnyDict): Additional attributes for the log. + container (str | None): The container associated with the log. + """ + timestamp: datetime body: str severity: str @@ -77,6 +130,24 @@ class TraceLog(BaseModel): class TraceSpan(BaseModel): + """Represents a span within a trace. + + Attributes: + timestamp (datetime): The timestamp of the span. + duration (int): The duration of the span in milliseconds. + trace_id (str): The trace ID of the span. + span_id (str): The span ID of the span. + parent_span_id (str | None): The parent span ID, if any. + service_name (str | None): The name of the service associated with the span. + status (SpanStatus): The status of the span. + exception (SpanException | None): The exception associated with the span, if any. + name (str): The name of the span. + attributes (AnyDict): Additional attributes for the span. + resource_attributes (AnyDict): Resource-specific attributes for the span. + events (list[SpanEvent]): A list of events associated with the span. + links (list[SpanLink]): A list of links to other spans. + """ + timestamp: datetime duration: int trace_id: str @@ -93,6 +164,15 @@ class TraceSpan(BaseModel): class Metric(BaseModel): + """Represents a metric associated with a task or span. + + Attributes: + value (float): The value of the metric. + step (int): The step number associated with the metric. + timestamp (datetime): The timestamp of the metric. + attributes (AnyDict): Additional attributes for the metric. + """ + value: float step: int timestamp: datetime @@ -100,12 +180,30 @@ class Metric(BaseModel): class ObjectRef(BaseModel): + """Represents a reference to an object. + + Attributes: + name (str): The name of the object. + label (str): The label of the object. + hash (str): The hash of the object. + """ + name: str label: str hash: str class ObjectUri(BaseModel): + """Represents an object stored as a URI. + + Attributes: + hash (str): The hash of the object. + schema_hash (str): The schema hash of the object. + uri (str): The URI of the object. + size (int): The size of the object in bytes. + type (Literal["uri"]): The type of the object, always "uri". + """ + hash: str schema_hash: str uri: str @@ -114,6 +212,15 @@ class ObjectUri(BaseModel): class ObjectVal(BaseModel): + """Represents an object stored as a value. + + Attributes: + hash (str): The hash of the object. + schema_hash (str): The schema hash of the object. + value (Any): The value of the object. + type (Literal["val"]): The type of the object, always "val". + """ + hash: str schema_hash: str value: t.Any @@ -124,12 +231,41 @@ class ObjectVal(BaseModel): class V0Object(BaseModel): + """Represents a backward-compatible object. + + Attributes: + name (str): The name of the object. + label (str): The label of the object. + value (Any): The value of the object. + """ + name: str label: str value: t.Any class Run(BaseModel): + """Represents a run of a task or process. + + Attributes: + id (ULID): The unique identifier for the run. + name (str): The name of the run. + span_id (str): The span ID associated with the run. + trace_id (str): The trace ID associated with the run. + timestamp (datetime): The timestamp of the run. + duration (int): The duration of the run in milliseconds. + status (SpanStatus): The status of the run. + exception (SpanException | None): The exception associated with the run, if any. + tags (set[str]): A set of tags associated with the run. + params (AnyDict): Parameters associated with the run. + metrics (dict[str, list[Metric]]): Metrics associated with the run. + inputs (list[ObjectRef]): Input objects for the run. + outputs (list[ObjectRef]): Output objects for the run. + objects (dict[str, Object]): Additional objects associated with the run. + object_schemas (AnyDict): Schemas for the objects. + schema_ (AnyDict): The schema of the run. + """ + id: ULID name: str span_id: str @@ -149,6 +285,30 @@ class Run(BaseModel): class Task(BaseModel): + """Represents a task within the system. + + Attributes: + name (str): The name of the task. + span_id (str): The span ID associated with the task. + trace_id (str): The trace ID associated with the task. + parent_span_id (str | None): The parent span ID, if any. + parent_task_span_id (str | None): The parent task span ID, if any. + timestamp (datetime): The timestamp of the task. + duration (int): The duration of the task in milliseconds. + status (SpanStatus): The status of the task. + exception (SpanException | None): The exception associated with the task, if any. + tags (set[str]): A set of tags associated with the task. + params (AnyDict): Parameters associated with the task. + metrics (dict[str, list[Metric]]): Metrics associated with the task. + inputs (list[ObjectRef] | list[V0Object]): Input objects for the task. + outputs (list[ObjectRef] | list[V0Object]): Output objects for the task. + schema_ (AnyDict): The schema of the task. + attributes (AnyDict): Additional attributes for the task. + resource_attributes (AnyDict): Resource-specific attributes for the task. + events (list[SpanEvent]): A list of events associated with the task. + links (list[SpanLink]): A list of links to other spans. + """ + name: str span_id: str trace_id: str @@ -171,6 +331,19 @@ class Task(BaseModel): class Project(BaseModel): + """Represents a project within the system. + + Attributes: + id (UUID): The unique identifier for the project. + key (str): The key associated with the project. + name (str): The name of the project. + description (str | None): A description of the project. + created_at (datetime): The timestamp when the project was created. + updated_at (datetime): The timestamp when the project was last updated. + run_count (int): The number of runs associated with the project. + last_run (Run | None): The last run associated with the project, if any. + """ + id: UUID key: str name: str @@ -181,25 +354,44 @@ class Project(BaseModel): last_run: Run | None -# Derived types +class TaskTree(BaseModel): + """Represents a tree structure of tasks. + Attributes: + task (Task): The root task of the tree. + children (list[TaskTree]): The child tasks of the root task. + """ -class TaskTree(BaseModel): task: Task children: list["TaskTree"] = [] class SpanTree(BaseModel): - """Tree representation of a trace span with its children""" + """Represents a tree structure of spans. + + Attributes: + span (Task | TraceSpan): The root span of the tree. + children (list[SpanTree]): The child spans of the root span. + """ span: Task | TraceSpan children: list["SpanTree"] = [] -# User data credentials - - class UserDataCredentials(BaseModel): + """Represents user data credentials for accessing resources. + + Attributes: + access_key_id (str): The access key ID. + secret_access_key (str): The secret access key. + session_token (str): The session token. + expiration (datetime): The expiration time of the credentials. + region (str): The region associated with the credentials. + bucket (str): The bucket associated with the credentials. + prefix (str): The prefix associated with the credentials. + endpoint (str | None): The endpoint associated with the credentials, if any. + """ + access_key_id: str secret_access_key: str session_token: str diff --git a/dreadnode/artifact/__init__.py b/dreadnode/artifact/__init__.py index e69de29b..f08a0fc3 100644 --- a/dreadnode/artifact/__init__.py +++ b/dreadnode/artifact/__init__.py @@ -0,0 +1,15 @@ +"""Module for managing artifacts in the Dreadnode SDK. + +This module provides functionality for handling artifacts, which may include +creating, retrieving, updating, and deleting artifact-related data. + +Modules: + (List submodules or classes if applicable, e.g., artifact_manager, artifact_utils) + +Example: + Import the module and use its functionality as follows: + + from dreadnode.artifact import artifact_manager + + artifact = artifact_manager.create_artifact(name="example") +""" diff --git a/dreadnode/constants.py b/dreadnode/constants.py index 70c70642..f5aec52f 100644 --- a/dreadnode/constants.py +++ b/dreadnode/constants.py @@ -1,3 +1,24 @@ +"""Constants for the Dreadnode SDK. + +This module defines environment variable names and default values used +throughout the Dreadnode SDK. These constants are used for configuration +and managing default behaviors. + +Attributes: + ENV_SERVER_URL (str): The environment variable for the Dreadnode server URL. + ENV_SERVER (str): An alternative environment variable for the server URL. + ENV_API_TOKEN (str): The environment variable for the API token. + ENV_API_KEY (str): An alternative environment variable for the API token. + ENV_LOCAL_DIR (str): The environment variable for the local directory path. + ENV_PROJECT (str): The environment variable for the project name. + + DEFAULT_SERVER_URL (str): The default URL for the Dreadnode server. + DEFAULT_LOCAL_OBJECT_DIR (str): The default directory for local objects. + + MAX_INLINE_OBJECT_BYTES (int): The maximum size (in bytes) for inline objects + in S3 storage. +""" + # Environment variable names ENV_SERVER_URL = "DREADNODE_SERVER_URL" diff --git a/dreadnode/integrations/__init__.py b/dreadnode/integrations/__init__.py index e69de29b..90f421bf 100644 --- a/dreadnode/integrations/__init__.py +++ b/dreadnode/integrations/__init__.py @@ -0,0 +1,16 @@ +"""Module for managing integrations in the Dreadnode SDK. + +This module provides functionality for handling integrations with external +services or systems. It may include tools for configuring, enabling, and +managing these integrations. + +Modules: + (List submodules or classes if applicable, e.g., integration_manager, integration_utils) + +Example: + Import the module and use its functionality as follows: + + from dreadnode.integrations import integration_manager + + integration = integration_manager.enable_integration(name="example_service") +""" diff --git a/dreadnode/integrations/transformers.py b/dreadnode/integrations/transformers.py index 2df908c3..38883dea 100644 --- a/dreadnode/integrations/transformers.py +++ b/dreadnode/integrations/transformers.py @@ -5,7 +5,11 @@ import typing as t -from transformers.trainer_callback import TrainerCallback, TrainerControl, TrainerState +from transformers.trainer_callback import ( + TrainerCallback, + TrainerControl, + TrainerState, +) from transformers.training_args import TrainingArguments import dreadnode as dn @@ -15,8 +19,22 @@ # ruff: noqa: ARG002 +""" +This module provides an integration with the `transformers` library by implementing a +custom `TrainerCallback` for logging metrics and parameters to Dreadnode during training. +""" + def _clean_keys(data: dict[str, t.Any]) -> dict[str, t.Any]: + """ + Cleans the keys of a dictionary by replacing certain prefixes with slashes. + + Args: + data (dict[str, t.Any]): The dictionary to clean. + + Returns: + dict[str, t.Any]: A new dictionary with cleaned keys. + """ cleaned: dict[str, t.Any] = {} for key, val in data.items(): _key = key.replace("eval_", "eval/").replace("test_", "test/").replace("train_", "train/") @@ -26,10 +44,15 @@ def _clean_keys(data: dict[str, t.Any]) -> dict[str, t.Any]: class DreadnodeCallback(TrainerCallback): """ - An implementation of the `TrainerCallback` interface for Dreadnode. + A custom `TrainerCallback` implementation for Dreadnode. + + This callback logs metrics and parameters to Dreadnode during training using the + `transformers` library or its derivatives (e.g., `trl`). - This callback is used to log metrics and parameters to Dreadnode during training inside - the `transformers` library or derivations (`trl`, etc.). + Attributes: + project (str | None): The project name for the Dreadnode run. + run_name (str | None): The name of the run. + tags (list[str]): A list of tags to associate with the run. """ def __init__( @@ -38,6 +61,14 @@ def __init__( run_name: str | None = None, tags: list[str] | None = None, ): + """ + Initializes the DreadnodeCallback. + + Args: + project (str | None): The project name for the Dreadnode run. + run_name (str | None): The name of the run. + tags (list[str] | None): A list of tags to associate with the run. + """ self.project = project self.run_name = run_name self.tags = tags or [] @@ -48,6 +79,9 @@ def __init__( self._step_span: Span | None = None def _shutdown(self) -> None: + """ + Shuts down the callback by closing any active spans or runs. + """ if self._step_span is not None: self._step_span.__exit__(None, None, None) self._step_span = None @@ -61,6 +95,14 @@ def _shutdown(self) -> None: self._run = None def _setup(self, args: TrainingArguments, state: TrainerState, model: t.Any) -> None: + """ + Sets up the callback by initializing the Dreadnode run and logging parameters. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + model (t.Any): The model being trained. + """ if self._initialized: return @@ -101,6 +143,16 @@ def on_train_begin( model: t.Any | None = None, **kwargs: t.Any, ) -> None: + """ + Called at the beginning of training. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + model (t.Any | None): The model being trained. + **kwargs (t.Any): Additional keyword arguments. + """ if not self._initialized: self._setup(args, state, model) @@ -111,6 +163,15 @@ def on_train_end( control: TrainerControl, **kwargs: t.Any, ) -> None: + """ + Called at the end of training. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + **kwargs (t.Any): Additional keyword arguments. + """ self._shutdown() def on_epoch_begin( @@ -120,6 +181,15 @@ def on_epoch_begin( control: TrainerControl, **kwargs: t.Any, ) -> None: + """ + Called at the beginning of an epoch. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + **kwargs (t.Any): Additional keyword arguments. + """ if self._run is None or state.epoch is None: return @@ -135,6 +205,15 @@ def on_epoch_end( control: TrainerControl, **kwargs: t.Any, ) -> None: + """ + Called at the end of an epoch. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + **kwargs (t.Any): Additional keyword arguments. + """ if self._epoch_span is not None: self._epoch_span.__exit__(None, None, None) self._epoch_span = None @@ -146,6 +225,15 @@ def on_step_begin( control: TrainerControl, **kwargs: t.Any, ) -> None: + """ + Called at the beginning of a training step. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + **kwargs (t.Any): Additional keyword arguments. + """ if self._run is None: return @@ -161,6 +249,15 @@ def on_step_end( control: TrainerControl, **kwargs: t.Any, ) -> None: + """ + Called at the end of a training step. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + **kwargs (t.Any): Additional keyword arguments. + """ if self._step_span is not None: self._step_span.__exit__(None, None, None) self._step_span = None @@ -173,6 +270,16 @@ def on_log( logs: dict[str, t.Any] | None = None, **kwargs: t.Any, ) -> None: + """ + Called when logging metrics. + + Args: + args (TrainingArguments): The training arguments. + state (TrainerState): The state of the trainer. + control (TrainerControl): The control object for the trainer. + logs (dict[str, t.Any] | None): The logs to process. + **kwargs (t.Any): Additional keyword arguments. + """ if self._run is None or logs is None: return diff --git a/dreadnode/main.py b/dreadnode/main.py index d3773e70..2b00fe0a 100644 --- a/dreadnode/main.py +++ b/dreadnode/main.py @@ -1,3 +1,20 @@ +""" +Dreadnode SDK + +This module provides the core functionality for the Dreadnode SDK, enabling +users to track tasks, runs, metrics, and artifacts in a structured and +configurable manner. It integrates with OpenTelemetry for tracing and +Logfire for logging. + +Classes: + Dreadnode: The core SDK class for configuring and interacting with Dreadnode. + DreadnodeConfigWarning: Warning for configuration-related issues. + DreadnodeUsageWarning: Warning for usage-related issues. + +Constants: + DEFAULT_INSTANCE: A default instance of the Dreadnode class. +""" + import contextlib import inspect import os @@ -77,9 +94,19 @@ class Dreadnode: """ The core Dreadnode SDK class. - A default instance of this class is created and can be used directly with `dreadnode.*`. - - Otherwise, you can create your own instance and configure it with `configure()`. + This class provides methods to configure the SDK, track tasks and runs, + log metrics, parameters, and artifacts, and interact with the Dreadnode API. + + Attributes: + server (str | None): The Dreadnode server URL. + token (str | None): The Dreadnode API token. + local_dir (str | Path | t.Literal[False]): The local directory for storing data. + project (str | None): The default project name for runs. + service_name (str | None): The service name for OpenTelemetry. + service_version (str | None): The service version for OpenTelemetry. + console (logfire.ConsoleOptions | t.Literal[False, True]): Console logging options. + send_to_logfire (bool | t.Literal["if-token-present"]): Whether to send data to Logfire. + otel_scope (str): The OpenTelemetry scope name. """ server: str | None @@ -105,6 +132,20 @@ def __init__( send_to_logfire: bool | t.Literal["if-token-present"] = "if-token-present", otel_scope: str = "dreadnode", ) -> None: + """ + Initializes a new instance of the Dreadnode class. + + Args: + server (str | None): The Dreadnode server URL. + token (str | None): The Dreadnode API token. + local_dir (str | Path | t.Literal[False]): The local directory for storing data. + project (str | None): The default project name for runs. + service_name (str | None): The service name for OpenTelemetry. + service_version (str | None): The service version for OpenTelemetry. + console (logfire.ConsoleOptions | t.Literal[False, True]): Console logging options. + send_to_logfire (bool | t.Literal["if-token-present"]): Whether to send data to Logfire. + otel_scope (str): The OpenTelemetry scope name. + """ self.server = server self.token = token self.local_dir = local_dir @@ -139,28 +180,22 @@ def configure( otel_scope: str = "dreadnode", ) -> None: """ - Configure the Dreadnode SDK and call `initialize()`. + Configures the Dreadnode SDK and initializes it. - This method should always be called before using the SDK. - - If `server` and `token` are not provided, the SDK will look in - the associated environment variables: - - - `DREADNODE_SERVER_URL` or `DREADNODE_SERVER` - - `DREADNODE_API_TOKEN` or `DREADNODE_API_KEY` + This method should be called before using the SDK. It sets up the + server, token, local directory, and other configuration options. Args: - server: The Dreadnode server URL. - token: The Dreadnode API token. - local_dir: The local directory to store data in. - project: The defautlt project name to associate all runs with. - service_name: The service name to use for OpenTelemetry. - service_version: The service version to use for OpenTelemetry. - console: Whether to log span information to the console. - send_to_logfire: Whether to send data to Logfire. - otel_scope: The OpenTelemetry scope name. + server (str | None): The Dreadnode server URL. + token (str | None): The Dreadnode API token. + local_dir (str | Path | t.Literal[False]): The local directory for storing data. + project (str | None): The default project name for runs. + service_name (str | None): The service name for OpenTelemetry. + service_version (str | None): The service version for OpenTelemetry. + console (logfire.ConsoleOptions | t.Literal[False, True]): Console logging options. + send_to_logfire (bool | t.Literal["if-token-present"]): Whether to send data to Logfire. + otel_scope (str): The OpenTelemetry scope name. """ - self._initialized = False self.server = server or os.environ.get(ENV_SERVER_URL) or os.environ.get(ENV_SERVER) @@ -186,9 +221,10 @@ def configure( def initialize(self) -> None: """ - Initialize the Dreadnode SDK. + Initializes the Dreadnode SDK. - This method is called automatically when you call `configure()`. + This method is called automatically by `configure()`. It sets up + OpenTelemetry components, Logfire configuration, and API clients. """ if self._initialized: return @@ -277,21 +313,27 @@ def initialize(self) -> None: @property def is_default(self) -> bool: + """ + Checks if this instance is the default Dreadnode instance. + + Returns: + bool: True if this is the default instance, False otherwise. + """ return self is DEFAULT_INSTANCE def api(self, *, server: str | None = None, token: str | None = None) -> ApiClient: """ - Get an API client based on the current configuration or the provided server and token. - - If the server and token are not provided, the method will use the current configuration - and `configure()` needs to be called first. + Retrieves an API client based on the current configuration. Args: - server: The server URL to use for the API client. - token: The API token to use for authentication. + server (str | None): The server URL for the API client. + token (str | None): The API token for authentication. Returns: - An ApiClient instance. + ApiClient: An instance of the API client. + + Raises: + RuntimeError: If the SDK is not configured or the API is unavailable. """ if server is not None and token is not None: return ApiClient(server, token) @@ -314,13 +356,9 @@ def _get_tracer(self, *, is_span_tracer: bool = True) -> "Tracer": @handle_internal_errors() def shutdown(self) -> None: """ - Shutdown any associate OpenTelemetry components and flush any pending spans. + Shuts down OpenTelemetry components and flushes pending spans. - It is not required to call this method, as the SDK will automatically - flush and shutdown when the process exits. - - However, if you want to ensure that all spans are flushed before - exiting, you can call this method manually. + This method ensures that all spans are flushed before exiting. """ if not self._initialized: return @@ -335,26 +373,15 @@ def span( **attributes: t.Any, ) -> Span: """ - Create a new OpenTelemety span. - - Spans are more lightweight than tasks, but still let you track - work being performed and view it in the UI. You cannot - log parameters, inputs, or outputs to spans. - - Example: - ``` - with dreadnode.span("my_span") as span: - # do some work here - pass - ``` + Creates a new OpenTelemetry span. Args: - name: The name of the span. - tags: A list of tags to attach to the span. - **attributes: A dictionary of attributes to attach to the span. + name (str): The name of the span. + tags (t.Sequence[str] | None): A list of tags to attach to the span. + **attributes (t.Any): Additional attributes for the span. Returns: - A Span object. + Span: A new span object. """ return Span( name=name, @@ -445,30 +472,20 @@ def task( **attributes: t.Any, ) -> TaskDecorator: """ - Create a new task from a function. - - Example: - ``` - @dreadnode.task(name="my_task") - async def my_task(x: int) -> int: - return x * 2 - - await my_task(2) - ``` + Creates a new task from a function. Args: - scorers: A list of scorers to attach to the task. These will be called after every execution - of the task and will be passed the task's output. - name: The name of the task. - label: The label of the task - useful for filtering in the UI. - log_params: Whether to log all, or specific, incoming arguments to the function as parameters. - log_inputs: Whether to log all, or specific, incoming arguments to the function as inputs. - log_output: Whether to log the result of the function as an output. - tags: A list of tags to attach to the task span. - **attributes: A dictionary of attributes to attach to the task span. + scorers (t.Sequence[Scorer[t.Any] | ScorerCallable[t.Any]] | None): A list of scorers for the task. + name (str | None): The name of the task. + label (str | None): The label of the task. + log_params (t.Sequence[str] | bool): Whether to log parameters. + log_inputs (t.Sequence[str] | bool): Whether to log inputs. + log_output (bool): Whether to log the output. + tags (t.Sequence[str] | None): A list of tags for the task. + **attributes (t.Any): Additional attributes for the task. Returns: - A new Task object. + TaskDecorator: A decorator for creating tasks. """ def make_task( @@ -625,7 +642,7 @@ def run( **attributes: t.Any, ) -> RunSpan: """ - Create a new run. + Creates a new run. Runs are the main way to track work in Dreadnode. They are associated with a specific project and can have parameters, @@ -641,13 +658,16 @@ def run( ``` Args: - name: The name of the run. If not provided, a random name will be generated. - tags: A list of tags to attach to the run. - params: A dictionary of parameters to attach to the run. - project: The project name to associate the run with. If not provided, + name (str | None): The name of the run. If not provided, a random name will be generated. + tags (t.Sequence[str] | None): A list of tags to attach to the run. + params (AnyDict | None): A dictionary of parameters to attach to the run. + project (str | None): The project name to associate the run with. If not provided, the project passed to `configure()` will be used, or the run will be associated with a default project. - **attributes: Additional attributes to attach to the run span. + **attributes (t.Any): Additional attributes to attach to the run span. + + Returns: + RunSpan: A new run object. """ if not self._initialized: self.initialize() @@ -848,6 +868,19 @@ def log_metric( attributes: JsonDict | None = None, to: ToObject = "task-or-run", ) -> None: + """ + Logs a metric to the current task or run. + + Args: + key (str): The name of the metric. + value (float | bool | Metric): The value of the metric. + step (int): The step of the metric. + origin (t.Any | None): The origin of the metric. + timestamp (datetime | None): The timestamp of the metric. + mode (MetricAggMode | None): The aggregation mode for the metric. + attributes (JsonDict | None): Additional attributes for the metric. + to (ToObject): The target object to log the metric to. + """ task = current_task_span.get() run = current_run_span.get() @@ -899,8 +932,7 @@ def log_artifact( ``` Args: - local_uri: The local path to the file to upload. - to: The target object to log the artifact to. Only "run" is supported. + local_uri (str | Path): The local path to the file or directory to upload. """ if (run := current_run_span.get()) is None: raise RuntimeError("log_artifact() must be called within a run") @@ -935,13 +967,20 @@ async def my_task(x: int) -> int: await my_task(2) ``` + + Args: + name (str): The name of the input. + value (JsonValue): The value of the input. + label (str | None): An optional label for the input. + to (ToObject): The target object to log the input to. Defaults to "task-or-run". + **attributes (t.Any): Additional attributes to attach to the input. """ task = current_task_span.get() run = current_run_span.get() target = (task or run) if to == "task-or-run" else run if target is None: - raise RuntimeError("log_inputs() must be called within a run") + raise RuntimeError("log_input() must be called within a run") target.log_input(name, value, label=label, **attributes) @@ -980,7 +1019,7 @@ def log_output( @dreadnode.task async def my_task(x: int) -> int: result = x * 2 - dreadnode.log_output("result", x * 2) + dreadnode.log_output("result", result) return result with dreadnode.run("my_run"): @@ -988,6 +1027,13 @@ async def my_task(x: int) -> int: dreadnode.log_output("other", 123) ``` + + Args: + name (str): The name of the output. + value (t.Any): The value of the output. + label (str | None): An optional label for the output. + to (ToObject): The target object to log the output to. Defaults to "task-or-run". + **attributes (JsonValue): Additional attributes to attach to the output. """ task = current_task_span.get() run = current_run_span.get() @@ -1033,12 +1079,12 @@ def link_objects(self, origin: t.Any, link: t.Any, **attributes: JsonValue) -> N ``` Args: - origin: The origin object to link from. - link: The linked object to link to. - **attributes: Additional attributes to attach to the link. + origin (t.Any): The origin object to link from. + link (t.Any): The linked object to link to. + **attributes (JsonValue): Additional attributes to attach to the link. """ if (run := current_run_span.get()) is None: - raise RuntimeError("link() must be called within a run") + raise RuntimeError("link_objects() must be called within a run") origin_hash = run.log_object(origin) link_hash = run.log_object(link) diff --git a/dreadnode/metric.py b/dreadnode/metric.py index 2fcaa3da..110cf47c 100644 --- a/dreadnode/metric.py +++ b/dreadnode/metric.py @@ -1,3 +1,24 @@ +""" +This module provides classes and methods for managing and reporting metrics. + +Metrics are used to track the state of a run, task, or object (input/output). +The `Metric` class represents a single metric, while the `Scorer` class is used +to generate metrics from callable functions. + +Classes: + Metric: Represents a single metric with value, step, timestamp, and attributes. + Scorer: Generates metrics from callable functions. + +Exceptions: + MetricWarning: A warning class for metric-related issues. + +Types: + MetricAggMode: Literal type for aggregation modes. + MetricDict: Dictionary type for storing metrics. + ScorerResult: Union type for scorer results. + ScorerCallable: Callable type for scorer functions. +""" + import inspect import typing as t from dataclasses import dataclass, field @@ -15,23 +36,25 @@ class MetricWarning(UserWarning): - pass + """A warning class for metric-related issues.""" @dataclass class Metric: """ - Any reported value regarding the state of a run, task, and optionally object (input/output). + Represents a single metric with value, step, timestamp, and attributes. + + Attributes: + value (float): The value of the metric, e.g., 0.5, 1.0, 2.0, etc. + step (int): The step value to indicate when this metric was reported. + timestamp (datetime): The timestamp when the metric was reported. + attributes (JsonDict): A dictionary of attributes to attach to the metric. """ value: float - "The value of the metric, e.g. 0.5, 1.0, 2.0, etc." step: int = 0 - "An step value to indicate when this metric was reported." timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc)) - "The timestamp when the metric was reported." attributes: JsonDict = field(default_factory=dict) - "A dictionary of attributes to attach to the metric." @classmethod def from_many( @@ -43,19 +66,14 @@ def from_many( """ Create a composite metric from individual values and weights. - This is useful for creating a metric that is the weighted average of multiple values. - The values should be a sequence of tuples, where each tuple contains the name of the metric, - the value of the metric, and the weight of the metric. - - The individual values will be reported in the attributes of the metric. - Args: - values: A sequence of tuples containing the name, value, and weight of each metric. - step: The step value to attach to the metric. + values (Sequence[tuple[str, float, float]]): A sequence of tuples containing + the name, value, and weight of each metric. + step (int): The step value to attach to the metric. **attributes: Additional attributes to attach to the metric. Returns: - A composite Metric + Metric: A composite metric. """ total = sum(value * weight for _, value, weight in values) weight = sum(weight for _, _, weight in values) @@ -65,14 +83,15 @@ def from_many( def apply_mode(self, mode: MetricAggMode, others: "list[Metric]") -> "Metric": """ Apply an aggregation mode to the metric. - This will modify the metric in place. + + This modifies the metric in place based on the specified mode. Args: - mode: The mode to apply. One of "sum", "min", "max", or "inc". - others: A list of other metrics to apply the mode to. + mode (MetricAggMode): The mode to apply. One of "sum", "min", "max", "count", or "avg". + others (list[Metric]): A list of other metrics to apply the mode to. Returns: - self + Metric: The modified metric. """ previous_mode = next((m.attributes.get("mode") for m in others), mode) if previous_mode is not None and mode != previous_mode: @@ -109,20 +128,26 @@ def apply_mode(self, mode: MetricAggMode, others: "list[Metric]") -> "Metric": @dataclass class Scorer(t.Generic[T]): - tracer: Tracer + """ + Generates metrics from callable functions. + + Attributes: + tracer (Tracer): The tracer to use for reporting metrics. + name (str): The name of the scorer, used for reporting metrics. + tags (Sequence[str]): A list of tags to attach to the metric. + attributes (dict[str, Any]): A dictionary of attributes to attach to the metric. + func (ScorerCallable[T]): The function to call to get the metric. + step (int): The step value to attach to metrics produced by this Scorer. + auto_increment_step (bool): Whether to automatically increment the step for each call. + """ + tracer: Tracer name: str - "The name of the scorer, used for reporting metrics." tags: t.Sequence[str] - "A list of tags to attach to the metric." attributes: dict[str, t.Any] - "A dictionary of attributes to attach to the metric." func: ScorerCallable[T] - "The function to call to get the metric." step: int = 0 - "The step value to attach to metrics produced by this Scorer." auto_increment_step: bool = False - "Whether to automatically increment the step for each time this scorer is called." @classmethod def from_callable( @@ -138,14 +163,14 @@ def from_callable( Create a scorer from a callable function. Args: - tracer: The tracer to use for reporting metrics. - func: The function to call to get the metric. - name: The name of the scorer, used for reporting metrics. - tags: A list of tags to attach to the metric. - **attributes: A dictionary of attributes to attach to the metric. + tracer (Tracer): The tracer to use for reporting metrics. + func (ScorerCallable[T] | Scorer[T]): The function to call to get the metric. + name (str | None): The name of the scorer, used for reporting metrics. + tags (Sequence[str] | None): A list of tags to attach to the metric. + **attributes: Additional attributes to attach to the metric. Returns: - A Scorer object. + Scorer[T]: A Scorer object. """ if isinstance(func, Scorer): if name is not None or attributes is not None: @@ -170,6 +195,7 @@ def from_callable( ) def __post_init__(self) -> None: + """Initialize the scorer's signature and name.""" self.__signature__ = inspect.signature(self.func) self.__name__ = self.name @@ -178,7 +204,7 @@ def clone(self) -> "Scorer[T]": Clone the scorer. Returns: - A new Scorer. + Scorer[T]: A new Scorer object with the same attributes. """ return Scorer( tracer=self.tracer, @@ -194,13 +220,11 @@ async def __call__(self, object: T) -> Metric: """ Execute the scorer and return the metric. - Any output value will be converted to a Metric object. - Args: - object: The object to score. + object (T): The object to score. Returns: - A Metric object. + Metric: A Metric object representing the result of the scoring function. """ from dreadnode.tracing.span import Span diff --git a/dreadnode/tracing/__init__.py b/dreadnode/tracing/__init__.py index e69de29b..2c8b64fa 100644 --- a/dreadnode/tracing/__init__.py +++ b/dreadnode/tracing/__init__.py @@ -0,0 +1,16 @@ +"""Module for managing tracing in the Dreadnode SDK. + +This module provides functionality for tracing operations within the SDK. +It may include tools for collecting, analyzing, and exporting trace data +to help monitor and debug the system. + +Modules: + (List submodules or classes if applicable, e.g., tracing_manager, tracing_utils) + +Example: + Import the module and use its functionality as follows: + + from dreadnode.tracing import tracing_manager + + tracing_manager.start_trace(operation="example_operation") +""" diff --git a/dreadnode/tracing/constants.py b/dreadnode/tracing/constants.py index 8f5dc281..0944c87d 100644 --- a/dreadnode/tracing/constants.py +++ b/dreadnode/tracing/constants.py @@ -1,3 +1,11 @@ +""" +This module defines constants used for tracing spans and events in the Dreadnode SDK. + +The constants include span attributes, event names, and event attributes, all of which +are namespaced under the `dreadnode` prefix. These constants are used to standardize +the structure and metadata of spans and events for tracing purposes. +""" + import typing as t SPAN_NAMESPACE = "dreadnode" diff --git a/dreadnode/tracing/exporters.py b/dreadnode/tracing/exporters.py index 007188a6..5e5a7895 100644 --- a/dreadnode/tracing/exporters.py +++ b/dreadnode/tracing/exporters.py @@ -1,3 +1,9 @@ +""" +This module provides classes for exporting metrics, spans, and logs to JSONL files +in OTLP format. It includes configurations for file paths and exporters for +different telemetry signals. +""" + import threading import typing as t from collections.abc import Sequence @@ -23,22 +29,43 @@ @dataclass class FileExportConfig: - """Configuration for signal exports to JSONL files.""" + """Configuration for signal exports to JSONL files. + + Attributes: + base_path (str | Path): The base directory where files will be stored. + prefix (str): A prefix to add to the filenames. + """ base_path: str | Path = Path.cwd() / ".dreadnode" prefix: str = "" def get_path(self, signal: str) -> Path: - """Get the file path for a specific signal type.""" + """Get the file path for a specific signal type. + + Args: + signal (str): The type of signal (e.g., "metrics", "traces", "logs"). + + Returns: + Path: The full path to the file for the given signal type. + """ base = Path(self.base_path) base.mkdir(parents=True, exist_ok=True) return base / f"{self.prefix}{signal}.jsonl" class FileMetricReader(MetricReader): - """MetricReader that writes metrics to a file in OTLP format.""" + """MetricReader that writes metrics to a file in OTLP format. + + Attributes: + config (FileExportConfig): Configuration for file export. + """ def __init__(self, config: FileExportConfig): + """Initializes the FileMetricReader. + + Args: + config (FileExportConfig): Configuration for file export. + """ super().__init__() self.config = config self._lock = threading.Lock() @@ -46,6 +73,11 @@ def __init__(self, config: FileExportConfig): @property def file(self) -> IO[str]: + """Lazily opens and returns the file for writing metrics. + + Returns: + IO[str]: The file object for writing metrics. + """ if not self._file: self._file = self.config.get_path("metrics").open("a") return self._file @@ -56,6 +88,13 @@ def _receive_metrics( timeout_millis: float = 10_000, # noqa: ARG002 **kwargs: t.Any, # noqa: ARG002 ) -> None: + """Receives and writes metrics data to the file. + + Args: + metrics_data (MetricsData): The metrics data to write. + timeout_millis (float): Timeout in milliseconds (unused). + **kwargs: Additional arguments (unused). + """ if metrics_data is None: return @@ -66,6 +105,7 @@ def _receive_metrics( self.file.write(json_str + "\n") self.file.flush() except Exception as e: # noqa: BLE001 + # BLE001: Catching Exception is generally discouraged, but here we want to catch all exceptions logger.error(f"Failed to export metrics: {e}") def shutdown( @@ -73,6 +113,12 @@ def shutdown( timeout_millis: float = 30_000, # noqa: ARG002 **kwargs: t.Any, # noqa: ARG002 ) -> None: + """Shuts down the metric reader and closes the file. + + Args: + timeout_millis (float): Timeout in milliseconds (unused). + **kwargs: Additional arguments (unused). + """ with self._lock: if self._file: self._file.close() @@ -80,20 +126,42 @@ def shutdown( class FileSpanExporter(SpanExporter): - """SpanExporter that writes spans to a file in OTLP format.""" + """SpanExporter that writes spans to a file in OTLP format. + + Attributes: + config (FileExportConfig): Configuration for file export. + """ def __init__(self, config: FileExportConfig): + """Initializes the FileSpanExporter. + + Args: + config (FileExportConfig): Configuration for file export. + """ self.config = config self._lock = threading.Lock() self._file: IO[str] | None = None @property def file(self) -> IO[str]: + """Lazily opens and returns the file for writing spans. + + Returns: + IO[str]: The file object for writing spans. + """ if not self._file: self._file = self.config.get_path("traces").open("a") return self._file def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult: + """Exports spans to the file. + + Args: + spans (Sequence[ReadableSpan]): The spans to export. + + Returns: + SpanExportResult: The result of the export operation. + """ try: encoded = encode_spans(spans) json_str = json_format.MessageToJson(encoded, indent=None) @@ -101,17 +169,24 @@ def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult: self.file.write(json_str + "\n") self.file.flush() except Exception as e: # noqa: BLE001 + # BLE001: Catching Exception is generally discouraged, but here we want to catch all exceptions logger.error(f"Failed to export spans: {e}") return SpanExportResult.FAILURE return SpanExportResult.SUCCESS - def force_flush( - self, - timeout_millis: float = 30_000, # noqa: ARG002 - ) -> bool: - return True # We flush above + def force_flush(self, timeout_millis: float = 30_000) -> bool: # noqa: ARG002 + """Forces a flush of the exporter. + + Args: + timeout_millis (float): Timeout in milliseconds (unused). + + Returns: + bool: Always returns True as the file is flushed during export. + """ + return True def shutdown(self) -> None: + """Shuts down the span exporter and closes the file.""" with self._lock: if self._file: self._file.close() @@ -119,20 +194,42 @@ def shutdown(self) -> None: class FileLogExporter(LogExporter): - """LogExporter that writes logs to a file in OTLP format.""" + """LogExporter that writes logs to a file in OTLP format. + + Attributes: + config (FileExportConfig): Configuration for file export. + """ def __init__(self, config: FileExportConfig): + """Initializes the FileLogExporter. + + Args: + config (FileExportConfig): Configuration for file export. + """ self.config = config self._lock = threading.Lock() self._file: IO[str] | None = None @property def file(self) -> IO[str]: + """Lazily opens and returns the file for writing logs. + + Returns: + IO[str]: The file object for writing logs. + """ if not self._file: self._file = self.config.get_path("logs").open("a") return self._file def export(self, batch: Sequence[LogData]) -> LogExportResult: + """Exports logs to the file. + + Args: + batch (Sequence[LogData]): The logs to export. + + Returns: + LogExportResult: The result of the export operation. + """ try: encoded = encode_logs(batch) json_str = json_format.MessageToJson(encoded, indent=None) @@ -140,17 +237,24 @@ def export(self, batch: Sequence[LogData]) -> LogExportResult: self.file.write(json_str + "\n") self.file.flush() except Exception as e: # noqa: BLE001 + # BLE001: Catching Exception is generally discouraged, but here we want to catch all exceptions logger.error(f"Failed to export logs: {e}") return LogExportResult.FAILURE return LogExportResult.SUCCESS - def force_flush( - self, - timeout_millis: float = 30_000, # noqa: ARG002 - ) -> bool: + def force_flush(self, timeout_millis: float = 30_000) -> bool: # noqa: ARG002 + """Forces a flush of the exporter. + + Args: + timeout_millis (float): Timeout in milliseconds (unused). + + Returns: + bool: Always returns True as the file is flushed during export. + """ return True def shutdown(self) -> None: + """Shuts down the log exporter and closes the file.""" with self._lock: if self._file: self._file.close() diff --git a/dreadnode/tracing/span.py b/dreadnode/tracing/span.py index 4e611ab7..1da3c535 100644 --- a/dreadnode/tracing/span.py +++ b/dreadnode/tracing/span.py @@ -1,3 +1,11 @@ +""" +This module provides classes and utilities for tracing spans in the Dreadnode SDK. + +It includes the `Span` base class and its specialized subclasses such as `RunSpan`, +`RunUpdateSpan`, and `TaskSpan`. These classes are used to manage and log tracing +information, metrics, parameters, and artifacts during the execution of tasks and runs. +""" + import logging import re import types @@ -80,6 +88,18 @@ class Span(ReadableSpan): + """ + Base class for tracing spans. + + Attributes: + name (str): The name of the span. + attributes (AnyDict): Attributes associated with the span. + tracer (Tracer): The tracer instance used for the span. + label (str | None): Optional label for the span. + type (SpanType): The type of the span (e.g., "span"). + tags (t.Sequence[str] | None): Optional tags for the span. + """ + def __init__( self, name: str, @@ -90,6 +110,17 @@ def __init__( type: SpanType = "span", tags: t.Sequence[str] | None = None, ) -> None: + """ + Initializes a Span instance. + + Args: + name (str): The name of the span. + attributes (AnyDict): Attributes associated with the span. + tracer (Tracer): The tracer instance used for the span. + label (str | None, optional): Optional label for the span. Defaults to None. + type (SpanType, optional): The type of the span. Defaults to "span". + tags (t.Sequence[str] | None, optional): Optional tags for the span. Defaults to None. + """ self._label = label or "" self._span_name = name self._pre_attributes = { @@ -111,6 +142,12 @@ def __getattr__(self, name: str) -> t.Any: return getattr(self._span, name) def __enter__(self) -> te.Self: + """ + Enters the span context. + + Returns: + te.Self: The span instance. + """ if self._span is None: self._span = self._tracer.start_span( name=self._span_name, @@ -132,6 +169,14 @@ def __exit__( exc_value: BaseException | None, traceback: types.TracebackType | None, ) -> None: + """ + Exits the span context. + + Args: + exc_type (type[BaseException] | None): The exception type, if any. + exc_value (BaseException | None): The exception value, if any. + traceback (types.TracebackType | None): The traceback, if any. + """ if self._token is None or self._span is None: return @@ -151,28 +196,64 @@ def __exit__( @property def span_id(self) -> str: + """ + Returns the span ID. + + Returns: + str: The span ID. + + Raises: + ValueError: If the span is not active. + """ if self._span is None: raise ValueError("Span is not active") return trace_api.format_span_id(self._span.get_span_context().span_id) @property def trace_id(self) -> str: + """ + Returns the trace ID. + + Returns: + str: The trace ID. + + Raises: + ValueError: If the span is not active. + """ if self._span is None: raise ValueError("Span is not active") return trace_api.format_trace_id(self._span.get_span_context().trace_id) @property def is_recording(self) -> bool: + """ + Checks if the span is recording. + + Returns: + bool: True if the span is recording, False otherwise. + """ if self._span is None: return False return self._span.is_recording() @property def tags(self) -> tuple[str, ...]: + """ + Gets the tags associated with the span. + + Returns: + tuple[str, ...]: The tags. + """ return tuple(self.get_attribute(SPAN_ATTRIBUTE_TAGS_, ())) @tags.setter def tags(self, new_tags: t.Sequence[str]) -> None: + """ + Sets the tags for the span. + + Args: + new_tags (t.Sequence[str]): The new tags. + """ self.set_attribute(SPAN_ATTRIBUTE_TAGS_, uniquify_sequence(new_tags)) def set_attribute( @@ -183,6 +264,15 @@ def set_attribute( schema: bool = True, raw: bool = False, ) -> None: + """ + Sets an attribute for the span. + + Args: + key (str): The attribute key. + value (t.Any): The attribute value. + schema (bool, optional): Whether to include the attribute in the schema. Defaults to True. + raw (bool, optional): Whether to store the raw value. Defaults to False. + """ self._added_attributes = True if schema and raw is False: self._schema[key] = create_json_schema(value, set()) @@ -192,15 +282,37 @@ def set_attribute( self._pre_attributes[key] = otel_value def set_attributes(self, attributes: AnyDict) -> None: + """ + Sets multiple attributes for the span. + + Args: + attributes (AnyDict): A dictionary of attributes to set. + """ for key, value in attributes.items(): self.set_attribute(key, value) def get_attributes(self) -> AnyDict: + """ + Gets all attributes of the span. + + Returns: + AnyDict: A dictionary of attributes. + """ if self._span is not None: return getattr(self._span, "attributes", {}) return self._pre_attributes def get_attribute(self, key: str, default: t.Any) -> t.Any: + """ + Gets a specific attribute of the span. + + Args: + key (str): The attribute key. + default (t.Any): The default value if the attribute is not found. + + Returns: + t.Any: The attribute value or the default value. + """ return self.get_attributes().get(key, default) def log_event( @@ -208,6 +320,13 @@ def log_event( name: str, attributes: AnyDict | None = None, ) -> None: + """ + Logs an event to the span. + + Args: + name (str): The name of the event. + attributes (AnyDict | None, optional): Attributes associated with the event. Defaults to None. + """ if self._span is not None: self._span.add_event( name, @@ -216,6 +335,18 @@ def log_event( class RunUpdateSpan(Span): + """ + A specialized span for updating run information. + + Attributes: + run_id (str): The ID of the run. + tracer (Tracer): The tracer instance. + project (str): The project name. + metrics (MetricDict | None): Optional metrics for the run. + params (JsonDict | None): Optional parameters for the run. + inputs (JsonDict | None): Optional inputs for the run. + """ + def __init__( self, run_id: str, @@ -226,6 +357,17 @@ def __init__( params: JsonDict | None = None, inputs: JsonDict | None = None, ) -> None: + """ + Initializes a RunUpdateSpan instance. + + Args: + run_id (str): The ID of the run. + tracer (Tracer): The tracer instance. + project (str): The project name. + metrics (MetricDict | None, optional): Optional metrics for the run. Defaults to None. + params (JsonDict | None, optional): Optional parameters for the run. Defaults to None. + inputs (JsonDict | None, optional): Optional inputs for the run. Defaults to None. + """ attributes: AnyDict = { SPAN_ATTRIBUTE_RUN_ID: run_id, SPAN_ATTRIBUTE_PROJECT: project, @@ -242,6 +384,19 @@ def __init__( class RunSpan(Span): + """ + A specialized span for managing and logging tracing information for a run. + + Attributes: + project (str): The project name associated with the run. + params (AnyDict): Parameters associated with the run. + metrics (MetricDict): Metrics associated with the run. + inputs (list[ObjectRef]): Input objects for the run. + outputs (list[ObjectRef]): Output objects for the run. + artifacts (list[DirectoryNode]): Artifacts associated with the run. + run_id (str): The unique identifier for the run. + """ + def __init__( self, name: str, @@ -255,6 +410,21 @@ def __init__( run_id: str | None = None, tags: t.Sequence[str] | None = None, ) -> None: + """ + Initializes a RunSpan instance. + + Args: + name (str): The name of the span. + project (str): The project name associated with the run. + attributes (AnyDict): Attributes associated with the span. + tracer (Tracer): The tracer instance used for the span. + file_system (AbstractFileSystem): The file system for artifact storage. + prefix_path (str): The prefix path for artifact storage. + params (AnyDict | None, optional): Parameters for the run. Defaults to None. + metrics (MetricDict | None, optional): Metrics for the run. Defaults to None. + run_id (str | None, optional): The unique identifier for the run. Defaults to None. + tags (t.Sequence[str] | None, optional): Tags for the span. Defaults to None. + """ self._params = params or {} self._metrics = metrics or {} self._objects: dict[str, Object] = {} @@ -323,6 +493,12 @@ def __exit__( current_run_span.reset(self._context_token) def push_update(self) -> None: + """ + Pushes updates for the run's parameters and metrics to the tracing system. + + If there are no changes to the parameters or metrics since the last push, + this method does nothing. + """ if self._span is None: return @@ -360,6 +536,18 @@ def log_object( event_name: str = EVENT_NAME_OBJECT, **attributes: JsonValue, ) -> str: + """ + Logs an object to the span. + + Args: + value (t.Any): The object to log. + label (str | None, optional): An optional label for the object. Defaults to None. + event_name (str, optional): The name of the event. Defaults to EVENT_NAME_OBJECT. + **attributes (JsonValue): Additional attributes for the event. + + Returns: + str: The hash of the logged object. + """ serialized = serialize(value) data_hash = serialized.data_hash schema_hash = serialized.schema_hash @@ -407,7 +595,15 @@ def _store_file_by_hash(self, data: bytes, full_path: str) -> str: return str(self._file_system.unstrip_protocol(full_path)) def _create_object(self, serialized: Serialized) -> Object: - """Create an ObjectVal or ObjectUri depending on size.""" + """ + Creates an ObjectVal or ObjectUri depending on the size of the serialized data. + + Args: + serialized (Serialized): The serialized object data. + + Returns: + Object: The created object (either ObjectVal or ObjectUri). + """ data = serialized.data data_bytes = serialized.data_bytes data_len = serialized.data_len @@ -433,6 +629,15 @@ def _create_object(self, serialized: Serialized) -> Object: ) def get_object(self, hash_: str) -> t.Any: + """ + Retrieves an object by its hash. + + Args: + hash_ (str): The hash of the object to retrieve. + + Returns: + t.Any: The retrieved object. + """ return self._objects[hash_] def link_objects( @@ -441,6 +646,14 @@ def link_objects( link_hash: str, **attributes: JsonValue, ) -> None: + """ + Logs a link between two objects in the span. + + Args: + object_hash (str): The hash of the source object. + link_hash (str): The hash of the linked object. + **attributes (JsonValue): Additional attributes for the link event. + """ self.log_event( name=EVENT_NAME_OBJECT_LINK, attributes={ @@ -552,6 +765,18 @@ def log_metric( mode: MetricAggMode | None = None, attributes: JsonDict | None = None, ) -> None: + """ + Logs a metric to the span. + + Args: + key (str): The key for the metric. + value (float | bool | Metric): The value of the metric. + step (int, optional): The step associated with the metric. Defaults to 0. + origin (t.Any | None, optional): The origin of the metric. Defaults to None. + timestamp (datetime | None, optional): The timestamp of the metric. Defaults to None. + mode (MetricAggMode | None, optional): The aggregation mode for the metric. Defaults to None. + attributes (JsonDict | None, optional): Additional attributes for the metric. Defaults to None. + """ metric = ( value if isinstance(value, Metric) @@ -596,6 +821,23 @@ def log_output( class TaskSpan(Span, t.Generic[R]): + """ + A specialized span for managing and logging tracing information for a task. + + Attributes: + name (str): The name of the task span. + attributes (AnyDict): Attributes associated with the task span. + run_id (str): The unique identifier for the run associated with the task. + tracer (Tracer): The tracer instance used for the task span. + label (str | None): An optional label for the task span. + params (AnyDict): Parameters associated with the task. + metrics (MetricDict): Metrics associated with the task. + tags (t.Sequence[str] | None): Optional tags for the task span. + inputs (list[ObjectRef]): Input objects for the task. + outputs (list[ObjectRef]): Output objects for the task. + output (R | Unset): The Python output of the task. + """ + def __init__( self, name: str, @@ -608,6 +850,19 @@ def __init__( metrics: MetricDict | None = None, tags: t.Sequence[str] | None = None, ) -> None: + """ + Initializes a TaskSpan instance. + + Args: + name (str): The name of the task span. + attributes (AnyDict): Attributes associated with the task span. + run_id (str): The unique identifier for the run associated with the task. + tracer (Tracer): The tracer instance used for the task span. + label (str | None, optional): An optional label for the task span. Defaults to None. + params (AnyDict | None, optional): Parameters for the task. Defaults to None. + metrics (MetricDict | None, optional): Metrics for the task. Defaults to None. + tags (t.Sequence[str] | None, optional): Tags for the task span. Defaults to None. + """ self._params = params or {} self._metrics = metrics or {} self._inputs: list[ObjectRef] = [] @@ -628,6 +883,15 @@ def __init__( super().__init__(name, attributes, tracer, type="task", label=label, tags=tags) def __enter__(self) -> te.Self: + """ + Enters the task span context. + + Returns: + te.Self: The task span instance. + + Raises: + RuntimeError: If a task span is started without an active run. + """ self._parent_task = current_task_span.get() if self._parent_task is not None: self.set_attribute(SPAN_ATTRIBUTE_PARENT_TASK_ID, self._parent_task.span_id) @@ -645,6 +909,14 @@ def __exit__( exc_value: BaseException | None, traceback: types.TracebackType | None, ) -> None: + """ + Exits the task span context. + + Args: + exc_type (type[BaseException] | None): The exception type, if any. + exc_value (BaseException | None): The exception value, if any. + traceback (types.TracebackType | None): The traceback, if any. + """ self.set_attribute(SPAN_ATTRIBUTE_PARAMS, self._params) self.set_attribute(SPAN_ATTRIBUTE_INPUTS, self._inputs, schema=False) self.set_attribute(SPAN_ATTRIBUTE_METRICS, self._metrics, schema=False) @@ -655,24 +927,60 @@ def __exit__( @property def run_id(self) -> str: + """ + Gets the run ID associated with the task span. + + Returns: + str: The run ID. + """ return str(self.get_attribute(SPAN_ATTRIBUTE_RUN_ID, "")) @property def parent_task_id(self) -> str: + """ + Gets the parent task ID, if any. + + Returns: + str: The parent task ID. + """ return str(self.get_attribute(SPAN_ATTRIBUTE_PARENT_TASK_ID, "")) @property def run(self) -> RunSpan: + """ + Gets the active run span associated with the task. + + Returns: + RunSpan: The active run span. + + Raises: + ValueError: If the task span is not in an active run. + """ if self._run is None: raise ValueError("Task span is not in an active run") return self._run @property def outputs(self) -> AnyDict: + """ + Gets the output objects logged to the task span. + + Returns: + AnyDict: A dictionary of output objects. + """ return {ref.name: self.run.get_object(ref.hash) for ref in self._outputs} @property def output(self) -> R: + """ + Gets the Python output of the task. + + Returns: + R: The Python output. + + Raises: + TypeError: If the task output is not set. + """ if isinstance(self._output, Unset): raise TypeError("Task output is not set") return self._output @@ -689,6 +997,18 @@ def log_output( label: str | None = None, **attributes: JsonValue, ) -> str: + """ + Logs an output object to the task span. + + Args: + name (str): The name of the output. + value (t.Any): The value of the output. + label (str | None, optional): An optional label for the output. Defaults to None. + **attributes (JsonValue): Additional attributes for the output. + + Returns: + str: The hash of the logged output. + """ label = label or re.sub(r"\W+", "_", name.lower()) hash_ = self.run.log_object( value, @@ -701,16 +1021,41 @@ def log_output( @property def params(self) -> AnyDict: + """ + Gets the parameters associated with the task. + + Returns: + AnyDict: A dictionary of task parameters. + """ return self._params def log_param(self, key: str, value: t.Any) -> None: + """ + Logs a single parameter to the task span. + + Args: + key (str): The parameter key. + value (t.Any): The parameter value. + """ self.log_params(**{key: value}) def log_params(self, **params: t.Any) -> None: + """ + Logs multiple parameters to the task span. + + Args: + **params (t.Any): The parameters to log. + """ self._params.update(params) @property def inputs(self) -> AnyDict: + """ + Gets the input objects logged to the task span. + + Returns: + AnyDict: A dictionary of input objects. + """ return {ref.name: self.run.get_object(ref.hash) for ref in self._inputs} def log_input( @@ -721,6 +1066,18 @@ def log_input( label: str | None = None, **attributes: JsonValue, ) -> str: + """ + Logs an input object to the task span. + + Args: + name (str): The name of the input. + value (t.Any): The value of the input. + label (str | None, optional): An optional label for the input. Defaults to None. + **attributes (JsonValue): Additional attributes for the input. + + Returns: + str: The hash of the logged input. + """ label = label or re.sub(r"\W+", "_", name.lower()) hash_ = self.run.log_object( value, @@ -733,6 +1090,12 @@ def log_input( @property def metrics(self) -> dict[str, list[Metric]]: + """ + Gets the metrics logged to the task span. + + Returns: + dict[str, list[Metric]]: A dictionary of metrics. + """ return self._metrics @t.overload @@ -769,6 +1132,18 @@ def log_metric( mode: MetricAggMode | None = None, attributes: JsonDict | None = None, ) -> None: + """ + Logs a metric to the task span. + + Args: + key (str): The key for the metric. + value (float | bool | Metric): The value of the metric. + step (int, optional): The step associated with the metric. Defaults to 0. + origin (t.Any | None, optional): The origin of the metric. Defaults to None. + timestamp (datetime | None, optional): The timestamp of the metric. Defaults to None. + mode (MetricAggMode | None, optional): The aggregation mode for the metric. Defaults to None. + attributes (JsonDict | None, optional): Additional attributes for the metric. Defaults to None. + """ metric = ( value if isinstance(value, Metric) @@ -798,6 +1173,16 @@ def log_metric( run.log_metric(f"{self._label}.{key}", metric) def get_average_metric_value(self, key: str | None = None) -> float: + """ + Calculates the average value of a metric or all metrics. + + Args: + key (str | None, optional): The key of the metric to calculate the average for. + If None, calculates the average for all metrics. Defaults to None. + + Returns: + float: The average value of the metric(s). + """ metrics = ( self._metrics.get(key, []) if key is not None @@ -811,10 +1196,28 @@ def get_average_metric_value(self, key: str | None = None) -> float: def prepare_otlp_attributes( attributes: AnyDict, ) -> dict[str, otel_types.AttributeValue]: + """ + Prepares attributes for OTLP export. + Converts attributes to a format suitable for OTLP export. + + Args: + attributes (AnyDict): A dictionary of attributes to prepare. + Returns: + dict[str, otel_types.AttributeValue]: A dictionary of prepared attributes. + """ return {key: prepare_otlp_attribute(value) for key, value in attributes.items()} def prepare_otlp_attribute(value: t.Any) -> otel_types.AttributeValue: + """ + Prepares a single attribute for OTLP export. + Converts the attribute to a format suitable for OTLP export. + + Args: + value (t.Any): The attribute value to prepare. + Returns: + otel_types.AttributeValue: The prepared attribute value. + """ if isinstance(value, str | int | bool | float): return value return json_dumps(value) diff --git a/dreadnode/util.py b/dreadnode/util.py index 30fdd233..fa0337cb 100644 --- a/dreadnode/util.py +++ b/dreadnode/util.py @@ -29,9 +29,18 @@ def safe_repr(obj: t.Any) -> str: """ - Return some kind of non-empty string representation of an object, catching exceptions. - """ + Safely generates a string representation of an object. + + This function attempts to generate a string representation of the given object + using `repr()`. If `repr()` raises an exception, it falls back to returning + a generic representation. + Args: + obj (Any): The object to represent. + + Returns: + str: A string representation of the object. + """ try: result = repr(obj) except Exception: # noqa: BLE001 @@ -47,6 +56,17 @@ def safe_repr(obj: t.Any) -> str: def log_internal_error() -> None: + """ + Logs an internal error in the Dreadnode application. + + This function captures and logs exceptions that occur internally in the + application. If running under pytest, it may re-raise the exception + depending on the test context. + + Raises: + Exception: Re-raises the exception if running under pytest and the + test context allows it. + """ try: current_test = os.environ.get("PYTEST_CURRENT_TEST", "") reraise = bool(current_test and "test_internal_exception" not in current_test) @@ -64,7 +84,15 @@ def log_internal_error() -> None: def _internal_error_exc_info() -> SysExcInfo: - """Returns an exc_info tuple with a nicely tweaked traceback.""" + """ + Retrieves an exception info tuple with an adjusted traceback. + + This function modifies the traceback to remove redundant frames and add + useful context, including up to three frames from user code. + + Returns: + SysExcInfo: A tuple containing the exception type, value, and traceback. + """ original_exc_info: SysExcInfo = sys.exc_info() exc_type, exc_val, original_tb = original_exc_info try: @@ -141,6 +169,15 @@ def _internal_error_exc_info() -> SysExcInfo: @contextmanager def handle_internal_errors() -> t.Iterator[None]: + """ + A context manager to handle internal errors gracefully. + + This context manager catches exceptions raised within its block and logs + them using `log_internal_error()`. + + Yields: + None: Allows the execution of the block within the context manager. + """ try: yield except Exception: # noqa: BLE001 From 8f674f58509d38df78c4284843981efaf3153c83 Mon Sep 17 00:00:00 2001 From: Brian Greunke Date: Fri, 9 May 2025 11:33:48 -0500 Subject: [PATCH 3/4] docs: updated autogenerated docs --- docs/dreadnode/api.mdx | 9 + docs/dreadnode/api/client.mdx | 141 ++++++- docs/dreadnode/api/models.mdx | 582 +++++++-------------------- docs/dreadnode/artifact.mdx | 8 + docs/dreadnode/constants.mdx | 19 + docs/dreadnode/integrations.mdx | 9 + docs/dreadnode/main.mdx | 192 ++++++--- docs/dreadnode/metric.mdx | 55 ++- docs/dreadnode/tracing.mdx | 9 + docs/dreadnode/tracing/constants.mdx | 6 + docs/dreadnode/tracing/exporters.mdx | 107 +++-- docs/dreadnode/tracing/span.mdx | 558 ++++++++++++++++++++++++- docs/dreadnode/util.mdx | 30 +- 13 files changed, 1156 insertions(+), 569 deletions(-) diff --git a/docs/dreadnode/api.mdx b/docs/dreadnode/api.mdx index 519fb648..36c5cbf4 100644 --- a/docs/dreadnode/api.mdx +++ b/docs/dreadnode/api.mdx @@ -10,3 +10,12 @@ groups: ["strikes"] **Source file:** `__init__.py` +This module initializes the `dreadnode.api` package. + +The `dreadnode.api` package provides the API layer for interacting with the +Dreadnode SDK. It includes modules and functions for handling requests, +responses, and other API-related functionality. + +Modules in this package should be imported and used to facilitate communication +with external services or internal components of the Dreadnode system. + diff --git a/docs/dreadnode/api/client.mdx b/docs/dreadnode/api/client.mdx index 0a35b111..6f5baeb0 100644 --- a/docs/dreadnode/api/client.mdx +++ b/docs/dreadnode/api/client.mdx @@ -10,6 +10,19 @@ groups: ["strikes"] **Source file:** `client.py` +This module provides the `ApiClient` class, which serves as a client for interacting + +with the Dreadnode API. It includes methods for managing projects, runs, tasks, and +exporting data in various formats. + +Dependencies: + - httpx + - pandas + - pydantic + - ulid + - dreadnode.util.logger + - dreadnode.version.VERSION + ## Classes @@ -19,13 +32,27 @@ groups: ["strikes"] Client for the Dreadnode API. +This class provides methods to interact with the Dreadnode API, including +managing projects, runs, tasks, and exporting data. + +**Parameters:** + +- **`_base_url`** (`str`): The base URL of the API. +- **`_client`** (`httpx.Client`): The HTTP client used for making requests. + #### Methods ##### `__init__` `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes the ApiClient. + +**Parameters:** + +- **`base_url`** (`str`): The base URL of the API. +- **`api_key`** (`str`): The API key for authentication. +- **`debug`** (`bool`) *(optional)*: Whether to enable debug logging. Defaults to False. Default: `False` --- @@ -33,73 +60,183 @@ Initialize self. See help(type(self)) for accurate signature. `export_metrics(...)` +Exports metric data for a specific project. + +**Parameters:** + +- **`project`** (`str`): The project identifier. +- **`filter`** (`str`) *(optional)*: A filter string. Defaults to None. Default: `None` +- **`status`** (`StatusFilter`) *(optional)*: The status filter. Defaults to "completed". Default: `"completed"` +- **`metrics`** (`list[str]`) *(optional)*: A list of metrics to include. Defaults to None. Default: `None` +- **`aggregations`** (`list[MetricAggregationType]`) *(optional)*: Aggregations to apply. Defaults to None. Default: `None` + +**Returns:** `pd.DataFrame` — A DataFrame containing the exported data. + --- ##### `export_parameters` `export_parameters(...)` +Exports parameter data for a specific project. + +**Parameters:** + +- **`project`** (`str`): The project identifier. +- **`filter`** (`str`) *(optional)*: A filter string. Defaults to None. Default: `None` +- **`status`** (`StatusFilter`) *(optional)*: The status filter. Defaults to "completed". Default: `"completed"` +- **`parameters`** (`list[str]`) *(optional)*: A list of parameters to include. Defaults to None. Default: `None` +- **`metrics`** (`list[str]`) *(optional)*: A list of metrics to include. Defaults to None. Default: `None` +- **`aggregations`** (`list[MetricAggregationType]`) *(optional)*: Aggregations to apply. Defaults to None. Default: `None` + +**Returns:** `pd.DataFrame` — A DataFrame containing the exported data. + --- ##### `export_runs` `export_runs(...)` +Exports run data for a specific project. + +**Parameters:** + +- **`project`** (`str`): The project identifier. +- **`filter`** (`str`) *(optional)*: A filter string. Defaults to None. Default: `None` +- **`status`** (`StatusFilter`) *(optional)*: The status filter. Defaults to "completed". Default: `"completed"` +- **`aggregations`** (`list[MetricAggregationType]`) *(optional)*: Aggregations to apply. Defaults to None. Default: `None` + +**Returns:** `pd.DataFrame` — A DataFrame containing the exported data. + --- ##### `export_timeseries` `export_timeseries(...)` +Exports timeseries data for a specific project. + +**Parameters:** + +- **`project`** (`str`): The project identifier. +- **`filter`** (`str`) *(optional)*: A filter string. Defaults to None. Default: `None` +- **`status`** (`StatusFilter`) *(optional)*: The status filter. Defaults to "completed". Default: `"completed"` +- **`metrics`** (`list[str]`) *(optional)*: A list of metrics to include. Defaults to None. Default: `None` +- **`time_axis`** (`TimeAxisType`) *(optional)*: The time axis type. Defaults to "relative". Default: `"relative"` +- **`aggregations`** (`list[TimeAggregationType]`) *(optional)*: Aggregations to apply. Defaults to None. Default: `None` + +**Returns:** `pd.DataFrame` — A DataFrame containing the exported data. + --- ##### `get_project` `get_project(...)` +Retrieves details of a specific project. + +**Parameters:** + +- **`project`** (`str`): The project identifier. + +**Returns:** `Project` — The Project object. + --- ##### `get_run` `get_run(...)` +Retrieves details of a specific run. + +**Parameters:** + +- **`run`** (`Union[str, ULID]`): The run identifier. + +**Returns:** `Run` — The Run object. + --- ##### `get_run_tasks` `get_run_tasks(...)` +Lists all tasks for a specific run. + +**Parameters:** + +- **`run`** (`Union[str, ULID]`): The run identifier. + +**Returns:** `list[Task]` — A list of Task objects. + --- ##### `get_run_trace` `get_run_trace(...)` +Retrieves the trace spans for a specific run. + +**Parameters:** + +- **`run`** (`Union[str, ULID]`): The run identifier. + +**Returns:** `Union[list[Task, TraceSpan]]` — A list of Task or TraceSpan objects. + --- ##### `get_user_data_credentials` `get_user_data_credentials(...)` +Retrieves user data credentials. + +**Returns:** `UserDataCredentials` — The user data credentials. + --- ##### `list_projects` `list_projects(...)` +Lists all projects. + +**Returns:** `list[Project]` — A list of Project objects. + --- ##### `list_runs` `list_runs(...)` +Lists all runs for a specific project. + +**Parameters:** + +- **`project`** (`str`): The project identifier. + +**Returns:** `list[Run]` — A list of Run objects. + --- ##### `request` `request(...)` -Make a request to the API. Raise an exception for non-200 status codes. +Makes an HTTP request to the API and raises exceptions for errors. + +**Parameters:** + +- **`method`** (`str`): The HTTP method (e.g., "GET", "POST"). +- **`path`** (`str`): The API endpoint path. +- **`params`** (`dict[str, t.Any]`) *(optional)*: Query parameters. Defaults to None. Default: `None` +- **`json_data`** (`dict[str, t.Any]`) *(optional)*: JSON payload. Defaults to None. Default: `None` + +**Returns:** `httpx.Response` — The HTTP response object. + +**Raises:** + +- `RuntimeError` — If the response status code indicates an error. --- diff --git a/docs/dreadnode/api/models.mdx b/docs/dreadnode/api/models.mdx index b9c09f51..5c6af2a5 100644 --- a/docs/dreadnode/api/models.mdx +++ b/docs/dreadnode/api/models.mdx @@ -10,6 +10,13 @@ groups: ["strikes"] **Source file:** `models.py` +This module defines the data models used in the Dreadnode API. + +The models are implemented using Pydantic's `BaseModel` and include various +types for representing tasks, spans, metrics, objects, and user-related data. +These models are used for serialization, validation, and type enforcement +throughout the API. + ## Classes @@ -17,601 +24,284 @@ groups: ["strikes"] **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a metric associated with a task or span. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`value`** (`float`): The value of the metric. +- **`step`** (`int`): The step number associated with the metric. +- **`timestamp`** (`datetime`): The timestamp of the metric. +- **`attributes`** (`AnyDict`): Additional attributes for the metric. ### Class `ObjectRef` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a reference to an object. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`name`** (`str`): The name of the object. +- **`label`** (`str`): The label of the object. +- **`hash`** (`str`): The hash of the object. ### Class `ObjectUri` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents an object stored as a URI. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`hash`** (`str`): The hash of the object. +- **`schema_hash`** (`str`): The schema hash of the object. +- **`uri`** (`str`): The URI of the object. +- **`size`** (`int`): The size of the object in bytes. +- **`type`** (`Literal["uri"]`): The type of the object, always "uri". ### Class `ObjectVal` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents an object stored as a value. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`hash`** (`str`): The hash of the object. +- **`schema_hash`** (`str`): The schema hash of the object. +- **`value`** (`Any`): The value of the object. +- **`type`** (`Literal["val"]`): The type of the object, always "val". ### Class `Project` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a project within the system. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`id`** (`UUID`): The unique identifier for the project. +- **`key`** (`str`): The key associated with the project. +- **`name`** (`str`): The name of the project. +- **`description`** (`Optional[str]`): A description of the project. +- **`created_at`** (`datetime`): The timestamp when the project was created. +- **`updated_at`** (`datetime`): The timestamp when the project was last updated. +- **`run_count`** (`int`): The number of runs associated with the project. +- **`last_run`** (`Optional[Run]`): The last run associated with the project, if any. ### Class `Run` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a run of a task or process. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`id`** (`ULID`): The unique identifier for the run. +- **`name`** (`str`): The name of the run. +- **`span_id`** (`str`): The span ID associated with the run. +- **`trace_id`** (`str`): The trace ID associated with the run. +- **`timestamp`** (`datetime`): The timestamp of the run. +- **`duration`** (`int`): The duration of the run in milliseconds. +- **`status`** (`SpanStatus`): The status of the run. +- **`exception`** (`Optional[SpanException]`): The exception associated with the run, if any. +- **`tags`** (`set[str]`): A set of tags associated with the run. +- **`params`** (`AnyDict`): Parameters associated with the run. +- **`metrics`** (`dict[str, list[Metric]]`): Metrics associated with the run. +- **`inputs`** (`list[ObjectRef]`): Input objects for the run. +- **`outputs`** (`list[ObjectRef]`): Output objects for the run. +- **`objects`** (`dict[str, Object]`): Additional objects associated with the run. +- **`object_schemas`** (`AnyDict`): Schemas for the objects. +- **`schema_`** (`AnyDict`): The schema of the run. ### Class `SpanEvent` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents an event within a span. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`timestamp`** (`datetime`): The timestamp of the event. +- **`name`** (`str`): The name of the event. +- **`attributes`** (`AnyDict`): Additional attributes associated with the event. ### Class `SpanException` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents an exception that occurred during a span. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`type`** (`str`): The type of the exception. +- **`message`** (`str`): The exception message. +- **`stacktrace`** (`str`): The stack trace of the exception. ### Class `SpanLink` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a link between spans. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`trace_id`** (`str`): The trace ID of the linked span. +- **`span_id`** (`str`): The span ID of the linked span. +- **`attributes`** (`AnyDict`): Additional attributes associated with the link. ### Class `SpanTree` **Inherits from:** `pydantic.main.BaseModel` -Tree representation of a trace span with its children +Represents a tree structure of spans. + +**Parameters:** + +- **`span`** (`Union[Task, TraceSpan]`): The root span of the tree. +- **`children`** (`list[SpanTree]`): The child spans of the root span. ### Class `Task` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a task within the system. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`name`** (`str`): The name of the task. +- **`span_id`** (`str`): The span ID associated with the task. +- **`trace_id`** (`str`): The trace ID associated with the task. +- **`parent_span_id`** (`Optional[str]`): The parent span ID, if any. +- **`parent_task_span_id`** (`Optional[str]`): The parent task span ID, if any. +- **`timestamp`** (`datetime`): The timestamp of the task. +- **`duration`** (`int`): The duration of the task in milliseconds. +- **`status`** (`SpanStatus`): The status of the task. +- **`exception`** (`Optional[SpanException]`): The exception associated with the task, if any. +- **`tags`** (`set[str]`): A set of tags associated with the task. +- **`params`** (`AnyDict`): Parameters associated with the task. +- **`metrics`** (`dict[str, list[Metric]]`): Metrics associated with the task. +- **`inputs`** (`Union[list[ObjectRef], list[V0Object]]`): Input objects for the task. +- **`outputs`** (`Union[list[ObjectRef], list[V0Object]]`): Output objects for the task. +- **`schema_`** (`AnyDict`): The schema of the task. +- **`attributes`** (`AnyDict`): Additional attributes for the task. +- **`resource_attributes`** (`AnyDict`): Resource-specific attributes for the task. +- **`events`** (`list[SpanEvent]`): A list of events associated with the task. +- **`links`** (`list[SpanLink]`): A list of links to other spans. ### Class `TaskTree` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a tree structure of tasks. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`task`** (`Task`): The root task of the tree. +- **`children`** (`list[TaskTree]`): The child tasks of the root task. ### Class `TraceLog` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a log entry within a trace. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`timestamp`** (`datetime`): The timestamp of the log entry. +- **`body`** (`str`): The log message body. +- **`severity`** (`str`): The severity level of the log. +- **`service`** (`Optional[str]`): The service associated with the log. +- **`trace_id`** (`Optional[str]`): The trace ID associated with the log. +- **`span_id`** (`Optional[str]`): The span ID associated with the log. +- **`attributes`** (`AnyDict`): Additional attributes for the log. +- **`container`** (`Optional[str]`): The container associated with the log. ### Class `TraceSpan` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a span within a trace. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`timestamp`** (`datetime`): The timestamp of the span. +- **`duration`** (`int`): The duration of the span in milliseconds. +- **`trace_id`** (`str`): The trace ID of the span. +- **`span_id`** (`str`): The span ID of the span. +- **`parent_span_id`** (`Optional[str]`): The parent span ID, if any. +- **`service_name`** (`Optional[str]`): The name of the service associated with the span. +- **`status`** (`SpanStatus`): The status of the span. +- **`exception`** (`Optional[SpanException]`): The exception associated with the span, if any. +- **`name`** (`str`): The name of the span. +- **`attributes`** (`AnyDict`): Additional attributes for the span. +- **`resource_attributes`** (`AnyDict`): Resource-specific attributes for the span. +- **`events`** (`list[SpanEvent]`): A list of events associated with the span. +- **`links`** (`list[SpanLink]`): A list of links to other spans. ### Class `UserAPIKey` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. - -**Parameters:** - -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +Represents a user's API key. ### Class `UserDataCredentials` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents user data credentials for accessing resources. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`access_key_id`** (`str`): The access key ID. +- **`secret_access_key`** (`str`): The secret access key. +- **`session_token`** (`str`): The session token. +- **`expiration`** (`datetime`): The expiration time of the credentials. +- **`region`** (`str`): The region associated with the credentials. +- **`bucket`** (`str`): The bucket associated with the credentials. +- **`prefix`** (`str`): The prefix associated with the credentials. +- **`endpoint`** (`Optional[str]`): The endpoint associated with the credentials, if any. ### Class `UserResponse` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a response containing user information. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`id`** (`UUID`): The unique identifier for the user. +- **`email_address`** (`str`): The user's email address. +- **`username`** (`str`): The user's username. +- **`api_key`** (`UserAPIKey`): The user's API key. ### Class `V0Object` **Inherits from:** `pydantic.main.BaseModel` -!!! abstract "Usage Documentation" - -[Models](../concepts/models.md) - -A base class for creating Pydantic models. +Represents a backward-compatible object. **Parameters:** -- **`__class_vars__`**: The names of the class variables defined on the model. -- **`__private_attributes__`**: Metadata about the private attributes of the model. -- **`__signature__`**: The synthesized `__init__` [`Signature`][inspect.Signature] of the model. -- **`__pydantic_complete__`**: Whether model building is completed, or if there are still undefined fields. -- **`__pydantic_core_schema__`**: The core schema of the model. -- **`__pydantic_custom_init__`**: Whether the model has a custom `__init__` function. -- **`__pydantic_decorators__`**: Metadata containing the decorators defined on the model. -This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1. -- **`__pydantic_generic_metadata__`**: Metadata for generic models; contains data used for a similar purpose to -__args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these. -- **`__pydantic_parent_namespace__`**: Parent namespace of the model, used for automatic rebuilding of models. -- **`__pydantic_post_init__`**: The name of the post-init method for the model, if defined. -- **`__pydantic_root_model__`**: Whether the model is a [`RootModel`][pydantic.root_model.RootModel]. -- **`__pydantic_serializer__`**: The `pydantic-core` `SchemaSerializer` used to dump instances of the model. -- **`__pydantic_validator__`**: The `pydantic-core` `SchemaValidator` used to validate instances of the model. -- **`__pydantic_fields__`**: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects. -- **`__pydantic_computed_fields__`**: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects. -- **`__pydantic_extra__`**: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra] -is set to `'allow'`. -- **`__pydantic_fields_set__`**: The names of fields explicitly set during instantiation. -- **`__pydantic_private__`**: Values of private attributes set on the model instance. +- **`name`** (`str`): The name of the object. +- **`label`** (`str`): The label of the object. +- **`value`** (`Any`): The value of the object. diff --git a/docs/dreadnode/artifact.mdx b/docs/dreadnode/artifact.mdx index cdb34c1d..29515365 100644 --- a/docs/dreadnode/artifact.mdx +++ b/docs/dreadnode/artifact.mdx @@ -10,3 +10,11 @@ groups: ["strikes"] **Source file:** `__init__.py` +Module for managing artifacts in the Dreadnode SDK. + +This module provides functionality for handling artifacts, which may include +creating, retrieving, updating, and deleting artifact-related data. + +Modules: + (List submodules or classes if applicable, e.g., artifact_manager, artifact_utils) + diff --git a/docs/dreadnode/constants.mdx b/docs/dreadnode/constants.mdx index e9cc3632..96c9b6aa 100644 --- a/docs/dreadnode/constants.mdx +++ b/docs/dreadnode/constants.mdx @@ -10,3 +10,22 @@ groups: ["strikes"] **Source file:** `constants.py` +Constants for the Dreadnode SDK. + +This module defines environment variable names and default values used +throughout the Dreadnode SDK. These constants are used for configuration +and managing default behaviors. + +**Parameters:** + +- **`ENV_SERVER_URL`** (`str`): The environment variable for the Dreadnode server URL. +- **`ENV_SERVER`** (`str`): An alternative environment variable for the server URL. +- **`ENV_API_TOKEN`** (`str`): The environment variable for the API token. +- **`ENV_API_KEY`** (`str`): An alternative environment variable for the API token. +- **`ENV_LOCAL_DIR`** (`str`): The environment variable for the local directory path. +- **`ENV_PROJECT`** (`str`): The environment variable for the project name. +- **`DEFAULT_SERVER_URL`** (`str`): The default URL for the Dreadnode server. +- **`DEFAULT_LOCAL_OBJECT_DIR`** (`str`): The default directory for local objects. +- **`MAX_INLINE_OBJECT_BYTES`** (`int`): The maximum size (in bytes) for inline objects +in S3 storage. + diff --git a/docs/dreadnode/integrations.mdx b/docs/dreadnode/integrations.mdx index 48bc5dee..fae8b22a 100644 --- a/docs/dreadnode/integrations.mdx +++ b/docs/dreadnode/integrations.mdx @@ -10,3 +10,12 @@ groups: ["strikes"] **Source file:** `__init__.py` +Module for managing integrations in the Dreadnode SDK. + +This module provides functionality for handling integrations with external +services or systems. It may include tools for configuring, enabling, and +managing these integrations. + +Modules: + (List submodules or classes if applicable, e.g., integration_manager, integration_utils) + diff --git a/docs/dreadnode/main.mdx b/docs/dreadnode/main.mdx index a5a64b6c..8667c498 100644 --- a/docs/dreadnode/main.mdx +++ b/docs/dreadnode/main.mdx @@ -10,6 +10,21 @@ groups: ["strikes"] **Source file:** `main.py` +Dreadnode SDK + +This module provides the core functionality for the Dreadnode SDK, enabling +users to track tasks, runs, metrics, and artifacts in a structured and +configurable manner. It integrates with OpenTelemetry for tracing and +Logfire for logging. + +Classes: + Dreadnode: The core SDK class for configuring and interacting with Dreadnode. + DreadnodeConfigWarning: Warning for configuration-related issues. + DreadnodeUsageWarning: Warning for usage-related issues. + +Constants: + DEFAULT_INSTANCE: A default instance of the Dreadnode class. + ## Classes @@ -19,9 +34,20 @@ groups: ["strikes"] The core Dreadnode SDK class. -A default instance of this class is created and can be used directly with `dreadnode.*`. +This class provides methods to configure the SDK, track tasks and runs, +log metrics, parameters, and artifacts, and interact with the Dreadnode API. -Otherwise, you can create your own instance and configure it with `configure()`. +**Parameters:** + +- **`server`** (`Optional[str]`): The Dreadnode server URL. +- **`token`** (`Optional[str]`): The Dreadnode API token. +- **`local_dir`** (`Union[str, Path, t.Literal[False]]`): The local directory for storing data. +- **`project`** (`Optional[str]`): The default project name for runs. +- **`service_name`** (`Optional[str]`): The service name for OpenTelemetry. +- **`service_version`** (`Optional[str]`): The service version for OpenTelemetry. +- **`console`** (`Union[logfire.ConsoleOptions, t.Literal[False, True]]`): Console logging options. +- **`send_to_logfire`** (`Union[bool, t.Literal["if-token-present"]]`): Whether to send data to Logfire. +- **`otel_scope`** (`str`): The OpenTelemetry scope name. #### Properties @@ -29,6 +55,10 @@ Otherwise, you can create your own instance and configure it with `configure()`. **Type:** `\` *(property)* +Checks if this instance is the default Dreadnode instance. + +**Returns:** `bool` — True if this is the default instance, False otherwise. + *Has: getter* --- @@ -47,7 +77,19 @@ Return self==value. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes a new instance of the Dreadnode class. + +**Parameters:** + +- **`server`** (`Optional[str]`): The Dreadnode server URL. +- **`token`** (`Optional[str]`): The Dreadnode API token. +- **`local_dir`** (`Union[str, Path, t.Literal[False]]`): The local directory for storing data. +- **`project`** (`Optional[str]`): The default project name for runs. +- **`service_name`** (`Optional[str]`): The service name for OpenTelemetry. +- **`service_version`** (`Optional[str]`): The service version for OpenTelemetry. +- **`console`** (`Union[logfire.ConsoleOptions, t.Literal[False, True]]`): Console logging options. +- **`send_to_logfire`** (`Union[bool, t.Literal["if-token-present"]]`): Whether to send data to Logfire. +- **`otel_scope`** (`str`): The OpenTelemetry scope name. --- @@ -63,17 +105,18 @@ Return repr(self). `api(...)` -Get an API client based on the current configuration or the provided server and token. - -If the server and token are not provided, the method will use the current configuration -and `configure()` needs to be called first. +Retrieves an API client based on the current configuration. **Parameters:** -- **`server`**: The server URL to use for the API client. -- **`token`**: The API token to use for authentication. +- **`server`** (`Optional[str]`): The server URL for the API client. +- **`token`** (`Optional[str]`): The API token for authentication. + +**Returns:** `ApiClient` — An instance of the API client. -**Returns:** An ApiClient instance. +**Raises:** + +- `RuntimeError` — If the SDK is not configured or the API is unavailable. --- @@ -81,27 +124,22 @@ and `configure()` needs to be called first. `configure(...)` -Configure the Dreadnode SDK and call `initialize()`. - -This method should always be called before using the SDK. +Configures the Dreadnode SDK and initializes it. -If `server` and `token` are not provided, the SDK will look in -the associated environment variables: - -- `DREADNODE_SERVER_URL` or `DREADNODE_SERVER` -- `DREADNODE_API_TOKEN` or `DREADNODE_API_KEY` +This method should be called before using the SDK. It sets up the +server, token, local directory, and other configuration options. **Parameters:** -- **`server`**: The Dreadnode server URL. -- **`token`**: The Dreadnode API token. -- **`local_dir`**: The local directory to store data in. -- **`project`**: The defautlt project name to associate all runs with. -- **`service_name`**: The service name to use for OpenTelemetry. -- **`service_version`**: The service version to use for OpenTelemetry. -- **`console`**: Whether to log span information to the console. -- **`send_to_logfire`**: Whether to send data to Logfire. -- **`otel_scope`**: The OpenTelemetry scope name. +- **`server`** (`Optional[str]`): The Dreadnode server URL. +- **`token`** (`Optional[str]`): The Dreadnode API token. +- **`local_dir`** (`Union[str, Path, t.Literal[False]]`): The local directory for storing data. +- **`project`** (`Optional[str]`): The default project name for runs. +- **`service_name`** (`Optional[str]`): The service name for OpenTelemetry. +- **`service_version`** (`Optional[str]`): The service version for OpenTelemetry. +- **`console`** (`Union[logfire.ConsoleOptions, t.Literal[False, True]]`): Console logging options. +- **`send_to_logfire`** (`Union[bool, t.Literal["if-token-present"]]`): Whether to send data to Logfire. +- **`otel_scope`** (`str`): The OpenTelemetry scope name. --- @@ -109,9 +147,10 @@ the associated environment variables: `initialize(...)` -Initialize the Dreadnode SDK. +Initializes the Dreadnode SDK. -This method is called automatically when you call `configure()`. +This method is called automatically by `configure()`. It sets up +OpenTelemetry components, Logfire configuration, and API clients. --- @@ -127,9 +166,9 @@ prompt and the resulting output. **Parameters:** -- **`origin`**: The origin object to link from. -- **`link`**: The linked object to link to. -- **`**attributes`**: Additional attributes to attach to the link. +- **`origin`** (`t.Any`): The origin object to link from. +- **`link`** (`t.Any`): The linked object to link to. +- **`**attributes`** (`JsonValue`): Additional attributes to attach to the link. --- @@ -143,8 +182,7 @@ This method uploads a local file or directory to the artifact storage associated **Parameters:** -- **`local_uri`**: The local path to the file to upload. -- **`to`**: The target object to log the artifact to. Only "run" is supported. +- **`local_uri`** (`Union[str, Path]`): The local path to the file or directory to upload. --- @@ -157,6 +195,14 @@ Log a single input to the current task or run. Inputs can be any runtime object, which are serialized, stored, and tracked in the Dreadnode UI. +**Parameters:** + +- **`name`** (`str`): The name of the input. +- **`value`** (`JsonValue`): The value of the input. +- **`label`** (`Optional[str]`): An optional label for the input. +- **`to`** (`ToObject`): The target object to log the input to. Defaults to "task-or-run". Default: `"task-or-run"` +- **`**attributes`** (`t.Any`): Additional attributes to attach to the input. + --- ##### `log_inputs` @@ -173,6 +219,19 @@ See `log_input()` for more details. `log_metric(...)` +Logs a metric to the current task or run. + +**Parameters:** + +- **`key`** (`str`): The name of the metric. +- **`value`** (`Union[float, bool, Metric]`): The value of the metric. +- **`step`** (`int`): The step of the metric. +- **`origin`** (`Optional[t.Any]`): The origin of the metric. +- **`timestamp`** (`Optional[datetime]`): The timestamp of the metric. +- **`mode`** (`Optional[MetricAggMode]`): The aggregation mode for the metric. +- **`attributes`** (`Optional[JsonDict]`): Additional attributes for the metric. +- **`to`** (`ToObject`): The target object to log the metric to. + --- ##### `log_output` @@ -184,6 +243,14 @@ Log a single output to the current task or run. Outputs can be any runtime object, which are serialized, stored, and tracked in the Dreadnode UI. +**Parameters:** + +- **`name`** (`str`): The name of the output. +- **`value`** (`t.Any`): The value of the output. +- **`label`** (`Optional[str]`): An optional label for the output. +- **`to`** (`ToObject`): The target object to log the output to. Defaults to "task-or-run". Default: `"task-or-run"` +- **`**attributes`** (`JsonValue`): Additional attributes to attach to the output. + --- ##### `log_outputs` @@ -251,7 +318,7 @@ automatically when the run is closed. `run(...)` -Create a new run. +Creates a new run. Runs are the main way to track work in Dreadnode. They are associated with a specific project and can have parameters, @@ -261,13 +328,15 @@ You cannot create runs inside other runs. **Parameters:** -- **`name`**: The name of the run. If not provided, a random name will be generated. -- **`tags`**: A list of tags to attach to the run. -- **`params`**: A dictionary of parameters to attach to the run. -- **`project`**: The project name to associate the run with. If not provided, +- **`name`** (`Optional[str]`): The name of the run. If not provided, a random name will be generated. +- **`tags`** (`Optional[t.Sequence[str]]`): A list of tags to attach to the run. +- **`params`** (`Optional[AnyDict]`): A dictionary of parameters to attach to the run. +- **`project`** (`Optional[str]`): The project name to associate the run with. If not provided, the project passed to `configure()` will be used, or the run will be associated with a default project. -- **`**attributes`**: Additional attributes to attach to the run span. +- **`**attributes`** (`t.Any`): Additional attributes to attach to the run span. + +**Returns:** `RunSpan` — A new run object. --- @@ -294,13 +363,9 @@ or add additional attributes to it. `shutdown(...)` -Shutdown any associate OpenTelemetry components and flush any pending spans. +Shuts down OpenTelemetry components and flushes pending spans. -It is not required to call this method, as the SDK will automatically -flush and shutdown when the process exits. - -However, if you want to ensure that all spans are flushed before -exiting, you can call this method manually. +This method ensures that all spans are flushed before exiting. --- @@ -308,19 +373,15 @@ exiting, you can call this method manually. `span(...)` -Create a new OpenTelemety span. - -Spans are more lightweight than tasks, but still let you track -work being performed and view it in the UI. You cannot -log parameters, inputs, or outputs to spans. +Creates a new OpenTelemetry span. **Parameters:** -- **`name`**: The name of the span. -- **`tags`**: A list of tags to attach to the span. -- **`**attributes`**: A dictionary of attributes to attach to the span. +- **`name`** (`str`): The name of the span. +- **`tags`** (`Optional[t.Sequence[str]]`): A list of tags to attach to the span. +- **`**attributes`** (`t.Any`): Additional attributes for the span. -**Returns:** A Span object. +**Returns:** `Span` — A new span object. --- @@ -328,21 +389,20 @@ log parameters, inputs, or outputs to spans. `task(...)` -Create a new task from a function. +Creates a new task from a function. **Parameters:** -- **`scorers`**: A list of scorers to attach to the task. These will be called after every execution -of the task and will be passed the task's output. -- **`name`**: The name of the task. -- **`label`**: The label of the task - useful for filtering in the UI. -- **`log_params`**: Whether to log all, or specific, incoming arguments to the function as parameters. -- **`log_inputs`**: Whether to log all, or specific, incoming arguments to the function as inputs. -- **`log_output`**: Whether to log the result of the function as an output. -- **`tags`**: A list of tags to attach to the task span. -- **`**attributes`**: A dictionary of attributes to attach to the task span. +- **`scorers`** (`Optional[t.Sequence[Scorer[t.Any] | ScorerCallable[t.Any]]]`): A list of scorers for the task. +- **`name`** (`Optional[str]`): The name of the task. +- **`label`** (`Optional[str]`): The label of the task. +- **`log_params`** (`Union[t.Sequence[str], bool]`): Whether to log parameters. +- **`log_inputs`** (`Union[t.Sequence[str], bool]`): Whether to log inputs. +- **`log_output`** (`bool`): Whether to log the output. +- **`tags`** (`Optional[t.Sequence[str]]`): A list of tags for the task. +- **`**attributes`** (`t.Any`): Additional attributes for the task. -**Returns:** A new Task object. +**Returns:** `TaskDecorator` — A decorator for creating tasks. --- diff --git a/docs/dreadnode/metric.mdx b/docs/dreadnode/metric.mdx index f3bcffe2..1d4e3e9c 100644 --- a/docs/dreadnode/metric.mdx +++ b/docs/dreadnode/metric.mdx @@ -10,6 +10,20 @@ groups: ["strikes"] **Source file:** `metric.py` +This module provides classes and methods for managing and reporting metrics. + +Metrics are used to track the state of a run, task, or object (input/output). +The `Metric` class represents a single metric, while the `Scorer` class is used +to generate metrics from callable functions. + +Classes: + Metric: Represents a single metric with value, step, timestamp, and attributes. + Scorer: Generates metrics from callable functions. + +**Raises:** + +- `MetricWarning` — A warning class for metric-related issues. + ## Classes @@ -17,7 +31,14 @@ groups: ["strikes"] **Inherits from:** `object` -Any reported value regarding the state of a run, task, and optionally object (input/output). +Represents a single metric with value, step, timestamp, and attributes. + +**Parameters:** + +- **`value`** (`float`): The value of the metric, e.g., 0.5, 1.0, 2.0, etc. +- **`step`** (`int`): The step value to indicate when this metric was reported. +- **`timestamp`** (`datetime`): The timestamp when the metric was reported. +- **`attributes`** (`JsonDict`): A dictionary of attributes to attach to the metric. #### Methods @@ -51,14 +72,14 @@ Return repr(self). Apply an aggregation mode to the metric. -This will modify the metric in place. +This modifies the metric in place based on the specified mode. **Parameters:** -- **`mode`**: The mode to apply. One of "sum", "min", "max", or "inc". -- **`others`**: A list of other metrics to apply the mode to. +- **`mode`** (`MetricAggMode`): The mode to apply. One of "sum", "min", "max", "count", or "avg". +- **`others`** (`list[Metric]`): A list of other metrics to apply the mode to. -**Returns:** self +**Returns:** `Metric` — The modified metric. --- @@ -67,14 +88,24 @@ This will modify the metric in place. **Inherits from:** `UserWarning` -Base class for warnings generated by user code. +A warning class for metric-related issues. ### Class `Scorer` **Inherits from:** `typing.Generic` -Scorer(tracer: opentelemetry.trace.Tracer, name: str, tags: Sequence[str], attributes: dict[str, typing.Any], func: Union[Callable[[~T], Awaitable[float | int | bool | dreadnode.metric.Metric]], Callable[[~T], float | int | bool | dreadnode.metric.Metric]], step: int = 0, auto_increment_step: bool = False) +Generates metrics from callable functions. + +**Parameters:** + +- **`tracer`** (`Tracer`): The tracer to use for reporting metrics. +- **`name`** (`str`): The name of the scorer, used for reporting metrics. +- **`tags`** (`Sequence[str]`): A list of tags to attach to the metric. +- **`attributes`** (`dict[str, Any]`): A dictionary of attributes to attach to the metric. +- **`func`** (`ScorerCallable[T]`): The function to call to get the metric. +- **`step`** (`int`): The step value to attach to metrics produced by this Scorer. +- **`auto_increment_step`** (`bool`): Whether to automatically increment the step for each call. #### Methods @@ -84,13 +115,11 @@ Scorer(tracer: opentelemetry.trace.Tracer, name: str, tags: Sequence[str], attri Execute the scorer and return the metric. -Any output value will be converted to a Metric object. - **Parameters:** -- **`object`**: The object to score. +- **`object`** (`T`): The object to score. -**Returns:** A Metric object. +**Returns:** `Metric` — A Metric object representing the result of the scoring function. --- @@ -114,6 +143,8 @@ Initialize self. See help(type(self)) for accurate signature. `__post_init__(...)` +Initialize the scorer's signature and name. + --- ##### `__repr__` @@ -130,7 +161,7 @@ Return repr(self). Clone the scorer. -**Returns:** A new Scorer. +**Returns:** `Scorer[T]` — A new Scorer object with the same attributes. --- diff --git a/docs/dreadnode/tracing.mdx b/docs/dreadnode/tracing.mdx index c9b50ccd..d71345da 100644 --- a/docs/dreadnode/tracing.mdx +++ b/docs/dreadnode/tracing.mdx @@ -10,3 +10,12 @@ groups: ["strikes"] **Source file:** `__init__.py` +Module for managing tracing in the Dreadnode SDK. + +This module provides functionality for tracing operations within the SDK. +It may include tools for collecting, analyzing, and exporting trace data +to help monitor and debug the system. + +Modules: + (List submodules or classes if applicable, e.g., tracing_manager, tracing_utils) + diff --git a/docs/dreadnode/tracing/constants.mdx b/docs/dreadnode/tracing/constants.mdx index 63360662..c70c73d8 100644 --- a/docs/dreadnode/tracing/constants.mdx +++ b/docs/dreadnode/tracing/constants.mdx @@ -10,3 +10,9 @@ groups: ["strikes"] **Source file:** `constants.py` +This module defines constants used for tracing spans and events in the Dreadnode SDK. + +The constants include span attributes, event names, and event attributes, all of which +are namespaced under the `dreadnode` prefix. These constants are used to standardize +the structure and metadata of spans and events for tracing purposes. + diff --git a/docs/dreadnode/tracing/exporters.mdx b/docs/dreadnode/tracing/exporters.mdx index ceecc662..8399dfc3 100644 --- a/docs/dreadnode/tracing/exporters.mdx +++ b/docs/dreadnode/tracing/exporters.mdx @@ -10,6 +10,11 @@ groups: ["strikes"] **Source file:** `exporters.py` +This module provides classes for exporting metrics, spans, and logs to JSONL files + +in OTLP format. It includes configurations for file paths and exporters for +different telemetry signals. + ## Classes @@ -19,6 +24,11 @@ groups: ["strikes"] Configuration for signal exports to JSONL files. +**Parameters:** + +- **`base_path`** (`Union[str, Path]`): The base directory where files will be stored. +- **`prefix`** (`str`): A prefix to add to the filenames. + #### Methods ##### `__eq__` @@ -51,6 +61,12 @@ Return repr(self). Get the file path for a specific signal type. +**Parameters:** + +- **`signal`** (`str`): The type of signal (e.g., "metrics", "traces", "logs"). + +**Returns:** `Path` — The full path to the file for the given signal type. + --- @@ -60,12 +76,20 @@ Get the file path for a specific signal type. LogExporter that writes logs to a file in OTLP format. +**Parameters:** + +- **`config`** (`FileExportConfig`): Configuration for file export. + #### Properties ##### `file` **Type:** `IO[str]` *(property)* +Lazily opens and returns the file for writing logs. + +**Returns:** `IO[str]` — The file object for writing logs. + *Has: getter* --- @@ -76,7 +100,11 @@ LogExporter that writes logs to a file in OTLP format. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes the FileLogExporter. + +**Parameters:** + +- **`config`** (`FileExportConfig`): Configuration for file export. --- @@ -84,13 +112,13 @@ Initialize self. See help(type(self)) for accurate signature. `export(...)` -Exports a batch of logs. +Exports logs to the file. **Parameters:** -- **`batch`**: The list of `LogData` objects to be exported +- **`batch`** (`Sequence[LogData]`): The logs to export. -**Returns:** The result of the export +**Returns:** `LogExportResult` — The result of the export operation. --- @@ -98,15 +126,21 @@ Exports a batch of logs. `force_flush(...)` +Forces a flush of the exporter. + +**Parameters:** + +- **`timeout_millis`** (`float`): Timeout in milliseconds (unused). + +**Returns:** `bool` — Always returns True as the file is flushed during export. + --- ##### `shutdown` `shutdown(...)` -Shuts down the exporter. - -Called when the SDK is shut down. +Shuts down the log exporter and closes the file. --- @@ -117,12 +151,20 @@ Called when the SDK is shut down. MetricReader that writes metrics to a file in OTLP format. +**Parameters:** + +- **`config`** (`FileExportConfig`): Configuration for file export. + #### Properties ##### `file` **Type:** `IO[str]` *(property)* +Lazily opens and returns the file for writing metrics. + +**Returns:** `IO[str]` — The file object for writing metrics. + *Has: getter* --- @@ -133,7 +175,11 @@ MetricReader that writes metrics to a file in OTLP format. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes the FileMetricReader. + +**Parameters:** + +- **`config`** (`FileExportConfig`): Configuration for file export. --- @@ -141,16 +187,12 @@ Initialize self. See help(type(self)) for accurate signature. `shutdown(...)` -Shuts down the MetricReader. This method provides a way +Shuts down the metric reader and closes the file. -for the MetricReader to do any cleanup required. A metric reader can -only be shutdown once, any subsequent calls are ignored and return -failure status. +**Parameters:** -When a `MetricReader` is registered on a -:class:`~opentelemetry.sdk.metrics.MeterProvider`, -:meth:`~opentelemetry.sdk.metrics.MeterProvider.shutdown` will invoke this -automatically. +- **`timeout_millis`** (`float`): Timeout in milliseconds (unused). +- **`**kwargs`**: Additional arguments (unused). --- @@ -161,12 +203,20 @@ automatically. SpanExporter that writes spans to a file in OTLP format. +**Parameters:** + +- **`config`** (`FileExportConfig`): Configuration for file export. + #### Properties ##### `file` **Type:** `IO[str]` *(property)* +Lazily opens and returns the file for writing spans. + +**Returns:** `IO[str]` — The file object for writing spans. + *Has: getter* --- @@ -177,7 +227,11 @@ SpanExporter that writes spans to a file in OTLP format. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes the FileSpanExporter. + +**Parameters:** + +- **`config`** (`FileExportConfig`): Configuration for file export. --- @@ -185,13 +239,13 @@ Initialize self. See help(type(self)) for accurate signature. `export(...)` -Exports a batch of telemetry data. +Exports spans to the file. **Parameters:** -- **`spans`**: The list of `opentelemetry.trace.Span` objects to be exported +- **`spans`** (`Sequence[ReadableSpan]`): The spans to export. -**Returns:** The result of the export +**Returns:** `SpanExportResult` — The result of the export operation. --- @@ -199,10 +253,13 @@ Exports a batch of telemetry data. `force_flush(...)` -Hint to ensure that the export of any spans the exporter has received +Forces a flush of the exporter. + +**Parameters:** -prior to the call to ForceFlush SHOULD be completed as soon as possible, preferably -before returning from this method. +- **`timeout_millis`** (`float`): Timeout in milliseconds (unused). + +**Returns:** `bool` — Always returns True as the file is flushed during export. --- @@ -210,9 +267,7 @@ before returning from this method. `shutdown(...)` -Shuts down the exporter. - -Called when the SDK is shut down. +Shuts down the span exporter and closes the file. --- diff --git a/docs/dreadnode/tracing/span.mdx b/docs/dreadnode/tracing/span.mdx index 197eff66..fc90f8a7 100644 --- a/docs/dreadnode/tracing/span.mdx +++ b/docs/dreadnode/tracing/span.mdx @@ -10,6 +10,12 @@ groups: ["strikes"] **Source file:** `span.py` +This module provides classes and utilities for tracing spans in the Dreadnode SDK. + +It includes the `Span` base class and its specialized subclasses such as `RunSpan`, +`RunUpdateSpan`, and `TaskSpan`. These classes are used to manage and log tracing +information, metrics, parameters, and artifacts during the execution of tasks and runs. + ## Classes @@ -17,10 +23,17 @@ groups: ["strikes"] **Inherits from:** `dreadnode.tracing.span.Span` -Provides read-only access to span attributes. +A specialized span for managing and logging tracing information for a run. -Users should NOT be creating these objects directly. `ReadableSpan`s are created as -a direct result from using the tracing pipeline via the `Tracer`. +**Parameters:** + +- **`project`** (`str`): The project name associated with the run. +- **`params`** (`AnyDict`): Parameters associated with the run. +- **`metrics`** (`MetricDict`): Metrics associated with the run. +- **`inputs`** (`list[ObjectRef]`): Input objects for the run. +- **`outputs`** (`list[ObjectRef]`): Output objects for the run. +- **`artifacts`** (`list[DirectoryNode]`): Artifacts associated with the run. +- **`run_id`** (`str`): The unique identifier for the run. #### Properties @@ -36,6 +49,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Checks if the span is recording. + +**Returns:** `bool` — True if the span is recording, False otherwise. + *Has: getter* --- @@ -76,6 +93,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the span ID. + +**Returns:** `str` — The span ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -84,6 +109,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `tuple[str, ...]` *(property)* +Gets the tags associated with the span. + +**Returns:** `tuple[str, ...]` — The tags. + *Has: getter, setter* --- @@ -92,6 +121,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the trace ID. + +**Returns:** `str` — The trace ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -102,12 +139,24 @@ a direct result from using the tracing pipeline via the `Tracer`. `__enter__(...)` +Enters the span context. + +**Returns:** `te.Self` — The span instance. + --- ##### `__exit__` `__exit__(...)` +Exits the span context. + +**Parameters:** + +- **`exc_type`** (`Optional[type[BaseException]]`): The exception type, if any. +- **`exc_value`** (`Optional[BaseException]`): The exception value, if any. +- **`traceback`** (`Optional[types.TracebackType]`): The traceback, if any. + --- ##### `__getattr__` @@ -120,7 +169,20 @@ a direct result from using the tracing pipeline via the `Tracer`. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes a RunSpan instance. + +**Parameters:** + +- **`name`** (`str`): The name of the span. +- **`project`** (`str`): The project name associated with the run. +- **`attributes`** (`AnyDict`): Attributes associated with the span. +- **`tracer`** (`Tracer`): The tracer instance used for the span. +- **`file_system`** (`AbstractFileSystem`): The file system for artifact storage. +- **`prefix_path`** (`str`): The prefix path for artifact storage. +- **`params`** (`Optional[AnyDict]`) *(optional)*: Parameters for the run. Defaults to None. Default: `None` +- **`metrics`** (`Optional[MetricDict]`) *(optional)*: Metrics for the run. Defaults to None. Default: `None` +- **`run_id`** (`Optional[str]`) *(optional)*: The unique identifier for the run. Defaults to None. Default: `None` +- **`tags`** (`Optional[t.Sequence[str]]`) *(optional)*: Tags for the span. Defaults to None. Default: `None` --- @@ -128,24 +190,53 @@ Initialize self. See help(type(self)) for accurate signature. `get_attribute(...)` +Gets a specific attribute of the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`default`** (`t.Any`): The default value if the attribute is not found. + +**Returns:** `t.Any` — The attribute value or the default value. + --- ##### `get_attributes` `get_attributes(...)` +Gets all attributes of the span. + +**Returns:** `AnyDict` — A dictionary of attributes. + --- ##### `get_object` `get_object(...)` +Retrieves an object by its hash. + +**Parameters:** + +- **`hash_`** (`str`): The hash of the object to retrieve. + +**Returns:** `t.Any` — The retrieved object. + --- ##### `link_objects` `link_objects(...)` +Logs a link between two objects in the span. + +**Parameters:** + +- **`object_hash`** (`str`): The hash of the source object. +- **`link_hash`** (`str`): The hash of the linked object. +- **`**attributes`** (`JsonValue`): Additional attributes for the link event. + --- ##### `log_artifact` @@ -172,6 +263,13 @@ Preserves directory structure and uses content hashing for deduplication. `log_event(...)` +Logs an event to the span. + +**Parameters:** + +- **`name`** (`str`): The name of the event. +- **`attributes`** (`Optional[AnyDict]`) *(optional)*: Attributes associated with the event. Defaults to None. Default: `None` + --- ##### `log_input` @@ -184,12 +282,35 @@ Preserves directory structure and uses content hashing for deduplication. `log_metric(...)` +Logs a metric to the span. + +**Parameters:** + +- **`key`** (`str`): The key for the metric. +- **`value`** (`Union[float, bool, Metric]`): The value of the metric. +- **`step`** (`int`) *(optional)*: The step associated with the metric. Defaults to 0. Default: `0` +- **`origin`** (`Optional[t.Any]`) *(optional)*: The origin of the metric. Defaults to None. Default: `None` +- **`timestamp`** (`Optional[datetime]`) *(optional)*: The timestamp of the metric. Defaults to None. Default: `None` +- **`mode`** (`Optional[MetricAggMode]`) *(optional)*: The aggregation mode for the metric. Defaults to None. Default: `None` +- **`attributes`** (`Optional[JsonDict]`) *(optional)*: Additional attributes for the metric. Defaults to None. Default: `None` + --- ##### `log_object` `log_object(...)` +Logs an object to the span. + +**Parameters:** + +- **`value`** (`t.Any`): The object to log. +- **`label`** (`Optional[str]`) *(optional)*: An optional label for the object. Defaults to None. Default: `None` +- **`event_name`** (`str`) *(optional)*: The name of the event. Defaults to EVENT_NAME_OBJECT. Default: `EVENT_NAME_OBJECT` +- **`**attributes`** (`JsonValue`): Additional attributes for the event. + +**Returns:** `str` — The hash of the logged object. + --- ##### `log_output` @@ -214,18 +335,38 @@ Preserves directory structure and uses content hashing for deduplication. `push_update(...)` +Pushes updates for the run's parameters and metrics to the tracing system. + +If there are no changes to the parameters or metrics since the last push, +this method does nothing. + --- ##### `set_attribute` `set_attribute(...)` +Sets an attribute for the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`value`** (`t.Any`): The attribute value. +- **`schema`** (`bool`) *(optional)*: Whether to include the attribute in the schema. Defaults to True. Default: `True` +- **`raw`** (`bool`) *(optional)*: Whether to store the raw value. Defaults to False. Default: `False` + --- ##### `set_attributes` `set_attributes(...)` +Sets multiple attributes for the span. + +**Parameters:** + +- **`attributes`** (`AnyDict`): A dictionary of attributes to set. + --- @@ -233,10 +374,16 @@ Preserves directory structure and uses content hashing for deduplication. **Inherits from:** `dreadnode.tracing.span.Span` -Provides read-only access to span attributes. +A specialized span for updating run information. -Users should NOT be creating these objects directly. `ReadableSpan`s are created as -a direct result from using the tracing pipeline via the `Tracer`. +**Parameters:** + +- **`run_id`** (`str`): The ID of the run. +- **`tracer`** (`Tracer`): The tracer instance. +- **`project`** (`str`): The project name. +- **`metrics`** (`Optional[MetricDict]`): Optional metrics for the run. +- **`params`** (`Optional[JsonDict]`): Optional parameters for the run. +- **`inputs`** (`Optional[JsonDict]`): Optional inputs for the run. #### Properties @@ -244,6 +391,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Checks if the span is recording. + +**Returns:** `bool` — True if the span is recording, False otherwise. + *Has: getter* --- @@ -252,6 +403,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the span ID. + +**Returns:** `str` — The span ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -260,6 +419,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `tuple[str, ...]` *(property)* +Gets the tags associated with the span. + +**Returns:** `tuple[str, ...]` — The tags. + *Has: getter, setter* --- @@ -268,6 +431,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the trace ID. + +**Returns:** `str` — The trace ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -278,12 +449,24 @@ a direct result from using the tracing pipeline via the `Tracer`. `__enter__(...)` +Enters the span context. + +**Returns:** `te.Self` — The span instance. + --- ##### `__exit__` `__exit__(...)` +Exits the span context. + +**Parameters:** + +- **`exc_type`** (`Optional[type[BaseException]]`): The exception type, if any. +- **`exc_value`** (`Optional[BaseException]`): The exception value, if any. +- **`traceback`** (`Optional[types.TracebackType]`): The traceback, if any. + --- ##### `__getattr__` @@ -296,7 +479,16 @@ a direct result from using the tracing pipeline via the `Tracer`. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes a RunUpdateSpan instance. + +**Parameters:** + +- **`run_id`** (`str`): The ID of the run. +- **`tracer`** (`Tracer`): The tracer instance. +- **`project`** (`str`): The project name. +- **`metrics`** (`Optional[MetricDict]`) *(optional)*: Optional metrics for the run. Defaults to None. Default: `None` +- **`params`** (`Optional[JsonDict]`) *(optional)*: Optional parameters for the run. Defaults to None. Default: `None` +- **`inputs`** (`Optional[JsonDict]`) *(optional)*: Optional inputs for the run. Defaults to None. Default: `None` --- @@ -304,30 +496,65 @@ Initialize self. See help(type(self)) for accurate signature. `get_attribute(...)` +Gets a specific attribute of the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`default`** (`t.Any`): The default value if the attribute is not found. + +**Returns:** `t.Any` — The attribute value or the default value. + --- ##### `get_attributes` `get_attributes(...)` +Gets all attributes of the span. + +**Returns:** `AnyDict` — A dictionary of attributes. + --- ##### `log_event` `log_event(...)` +Logs an event to the span. + +**Parameters:** + +- **`name`** (`str`): The name of the event. +- **`attributes`** (`Optional[AnyDict]`) *(optional)*: Attributes associated with the event. Defaults to None. Default: `None` + --- ##### `set_attribute` `set_attribute(...)` +Sets an attribute for the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`value`** (`t.Any`): The attribute value. +- **`schema`** (`bool`) *(optional)*: Whether to include the attribute in the schema. Defaults to True. Default: `True` +- **`raw`** (`bool`) *(optional)*: Whether to store the raw value. Defaults to False. Default: `False` + --- ##### `set_attributes` `set_attributes(...)` +Sets multiple attributes for the span. + +**Parameters:** + +- **`attributes`** (`AnyDict`): A dictionary of attributes to set. + --- @@ -335,10 +562,16 @@ Initialize self. See help(type(self)) for accurate signature. **Inherits from:** `opentelemetry.sdk.trace.ReadableSpan` -Provides read-only access to span attributes. +Base class for tracing spans. + +**Parameters:** -Users should NOT be creating these objects directly. `ReadableSpan`s are created as -a direct result from using the tracing pipeline via the `Tracer`. +- **`name`** (`str`): The name of the span. +- **`attributes`** (`AnyDict`): Attributes associated with the span. +- **`tracer`** (`Tracer`): The tracer instance used for the span. +- **`label`** (`Optional[str]`): Optional label for the span. +- **`type`** (`SpanType`): The type of the span (e.g., "span"). +- **`tags`** (`Optional[t.Sequence[str]]`): Optional tags for the span. #### Properties @@ -346,6 +579,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Checks if the span is recording. + +**Returns:** `bool` — True if the span is recording, False otherwise. + *Has: getter* --- @@ -354,6 +591,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the span ID. + +**Returns:** `str` — The span ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -362,6 +607,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `tuple[str, ...]` *(property)* +Gets the tags associated with the span. + +**Returns:** `tuple[str, ...]` — The tags. + *Has: getter, setter* --- @@ -370,6 +619,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the trace ID. + +**Returns:** `str` — The trace ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -380,12 +637,24 @@ a direct result from using the tracing pipeline via the `Tracer`. `__enter__(...)` +Enters the span context. + +**Returns:** `te.Self` — The span instance. + --- ##### `__exit__` `__exit__(...)` +Exits the span context. + +**Parameters:** + +- **`exc_type`** (`Optional[type[BaseException]]`): The exception type, if any. +- **`exc_value`** (`Optional[BaseException]`): The exception value, if any. +- **`traceback`** (`Optional[types.TracebackType]`): The traceback, if any. + --- ##### `__getattr__` @@ -398,7 +667,16 @@ a direct result from using the tracing pipeline via the `Tracer`. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes a Span instance. + +**Parameters:** + +- **`name`** (`str`): The name of the span. +- **`attributes`** (`AnyDict`): Attributes associated with the span. +- **`tracer`** (`Tracer`): The tracer instance used for the span. +- **`label`** (`Optional[str]`) *(optional)*: Optional label for the span. Defaults to None. Default: `None` +- **`type`** (`SpanType`) *(optional)*: The type of the span. Defaults to "span". Default: `"span"` +- **`tags`** (`Optional[t.Sequence[str]]`) *(optional)*: Optional tags for the span. Defaults to None. Default: `None` --- @@ -406,30 +684,65 @@ Initialize self. See help(type(self)) for accurate signature. `get_attribute(...)` +Gets a specific attribute of the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`default`** (`t.Any`): The default value if the attribute is not found. + +**Returns:** `t.Any` — The attribute value or the default value. + --- ##### `get_attributes` `get_attributes(...)` +Gets all attributes of the span. + +**Returns:** `AnyDict` — A dictionary of attributes. + --- ##### `log_event` `log_event(...)` +Logs an event to the span. + +**Parameters:** + +- **`name`** (`str`): The name of the event. +- **`attributes`** (`Optional[AnyDict]`) *(optional)*: Attributes associated with the event. Defaults to None. Default: `None` + --- ##### `set_attribute` `set_attribute(...)` +Sets an attribute for the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`value`** (`t.Any`): The attribute value. +- **`schema`** (`bool`) *(optional)*: Whether to include the attribute in the schema. Defaults to True. Default: `True` +- **`raw`** (`bool`) *(optional)*: Whether to store the raw value. Defaults to False. Default: `False` + --- ##### `set_attributes` `set_attributes(...)` +Sets multiple attributes for the span. + +**Parameters:** + +- **`attributes`** (`AnyDict`): A dictionary of attributes to set. + --- @@ -437,10 +750,21 @@ Initialize self. See help(type(self)) for accurate signature. **Inherits from:** `dreadnode.tracing.span.Span`, `typing.Generic` -Provides read-only access to span attributes. +A specialized span for managing and logging tracing information for a task. + +**Parameters:** -Users should NOT be creating these objects directly. `ReadableSpan`s are created as -a direct result from using the tracing pipeline via the `Tracer`. +- **`name`** (`str`): The name of the task span. +- **`attributes`** (`AnyDict`): Attributes associated with the task span. +- **`run_id`** (`str`): The unique identifier for the run associated with the task. +- **`tracer`** (`Tracer`): The tracer instance used for the task span. +- **`label`** (`Optional[str]`): An optional label for the task span. +- **`params`** (`AnyDict`): Parameters associated with the task. +- **`metrics`** (`MetricDict`): Metrics associated with the task. +- **`tags`** (`Optional[t.Sequence[str]]`): Optional tags for the task span. +- **`inputs`** (`list[ObjectRef]`): Input objects for the task. +- **`outputs`** (`list[ObjectRef]`): Output objects for the task. +- **`output`** (`Union[R, Unset]`): The Python output of the task. #### Properties @@ -448,6 +772,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `dict[str, Any]` *(property)* +Gets the input objects logged to the task span. + +**Returns:** `AnyDict` — A dictionary of input objects. + *Has: getter* --- @@ -456,6 +784,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Checks if the span is recording. + +**Returns:** `bool` — True if the span is recording, False otherwise. + *Has: getter* --- @@ -464,6 +796,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `dict[str, list[dreadnode.metric.Metric]]` *(property)* +Gets the metrics logged to the task span. + +**Returns:** `dict[str, list[Metric]]` — A dictionary of metrics. + *Has: getter* --- @@ -472,6 +808,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `~R` *(property)* +Gets the Python output of the task. + +**Returns:** `R` — The Python output. + +**Raises:** + +- `TypeError` — If the task output is not set. + *Has: getter, setter* --- @@ -480,6 +824,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `dict[str, Any]` *(property)* +Gets the output objects logged to the task span. + +**Returns:** `AnyDict` — A dictionary of output objects. + *Has: getter* --- @@ -488,6 +836,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `dict[str, Any]` *(property)* +Gets the parameters associated with the task. + +**Returns:** `AnyDict` — A dictionary of task parameters. + *Has: getter* --- @@ -496,6 +848,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Gets the parent task ID, if any. + +**Returns:** `str` — The parent task ID. + *Has: getter* --- @@ -504,6 +860,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Gets the active run span associated with the task. + +**Returns:** `RunSpan` — The active run span. + +**Raises:** + +- `ValueError` — If the task span is not in an active run. + *Has: getter* --- @@ -512,6 +876,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Gets the run ID associated with the task span. + +**Returns:** `str` — The run ID. + *Has: getter* --- @@ -520,6 +888,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the span ID. + +**Returns:** `str` — The span ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -528,6 +904,10 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `tuple[str, ...]` *(property)* +Gets the tags associated with the span. + +**Returns:** `tuple[str, ...]` — The tags. + *Has: getter, setter* --- @@ -536,6 +916,14 @@ a direct result from using the tracing pipeline via the `Tracer`. **Type:** `\` *(property)* +Returns the trace ID. + +**Returns:** `str` — The trace ID. + +**Raises:** + +- `ValueError` — If the span is not active. + *Has: getter* --- @@ -546,12 +934,28 @@ a direct result from using the tracing pipeline via the `Tracer`. `__enter__(...)` +Enters the task span context. + +**Returns:** `te.Self` — The task span instance. + +**Raises:** + +- `RuntimeError` — If a task span is started without an active run. + --- ##### `__exit__` `__exit__(...)` +Exits the task span context. + +**Parameters:** + +- **`exc_type`** (`Optional[type[BaseException]]`): The exception type, if any. +- **`exc_value`** (`Optional[BaseException]`): The exception value, if any. +- **`traceback`** (`Optional[types.TracebackType]`): The traceback, if any. + --- ##### `__getattr__` @@ -564,7 +968,18 @@ a direct result from using the tracing pipeline via the `Tracer`. `__init__(...)` -Initialize self. See help(type(self)) for accurate signature. +Initializes a TaskSpan instance. + +**Parameters:** + +- **`name`** (`str`): The name of the task span. +- **`attributes`** (`AnyDict`): Attributes associated with the task span. +- **`run_id`** (`str`): The unique identifier for the run associated with the task. +- **`tracer`** (`Tracer`): The tracer instance used for the task span. +- **`label`** (`Optional[str]`) *(optional)*: An optional label for the task span. Defaults to None. Default: `None` +- **`params`** (`Optional[AnyDict]`) *(optional)*: Parameters for the task. Defaults to None. Default: `None` +- **`metrics`** (`Optional[MetricDict]`) *(optional)*: Metrics for the task. Defaults to None. Default: `None` +- **`tags`** (`Optional[t.Sequence[str]]`) *(optional)*: Tags for the task span. Defaults to None. Default: `None` --- @@ -572,66 +987,157 @@ Initialize self. See help(type(self)) for accurate signature. `get_attribute(...)` +Gets a specific attribute of the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`default`** (`t.Any`): The default value if the attribute is not found. + +**Returns:** `t.Any` — The attribute value or the default value. + --- ##### `get_attributes` `get_attributes(...)` +Gets all attributes of the span. + +**Returns:** `AnyDict` — A dictionary of attributes. + --- ##### `get_average_metric_value` `get_average_metric_value(...)` +Calculates the average value of a metric or all metrics. + +**Parameters:** + +- **`key`** (`Optional[str]`) *(optional)*: The key of the metric to calculate the average for. +If None, calculates the average for all metrics. Defaults to None. + +**Returns:** `float` — The average value of the metric(s). + --- ##### `log_event` `log_event(...)` +Logs an event to the span. + +**Parameters:** + +- **`name`** (`str`): The name of the event. +- **`attributes`** (`Optional[AnyDict]`) *(optional)*: Attributes associated with the event. Defaults to None. Default: `None` + --- ##### `log_input` `log_input(...)` +Logs an input object to the task span. + +**Parameters:** + +- **`name`** (`str`): The name of the input. +- **`value`** (`t.Any`): The value of the input. +- **`label`** (`Optional[str]`) *(optional)*: An optional label for the input. Defaults to None. Default: `None` +- **`**attributes`** (`JsonValue`): Additional attributes for the input. + +**Returns:** `str` — The hash of the logged input. + --- ##### `log_metric` `log_metric(...)` +Logs a metric to the task span. + +**Parameters:** + +- **`key`** (`str`): The key for the metric. +- **`value`** (`Union[float, bool, Metric]`): The value of the metric. +- **`step`** (`int`) *(optional)*: The step associated with the metric. Defaults to 0. Default: `0` +- **`origin`** (`Optional[t.Any]`) *(optional)*: The origin of the metric. Defaults to None. Default: `None` +- **`timestamp`** (`Optional[datetime]`) *(optional)*: The timestamp of the metric. Defaults to None. Default: `None` +- **`mode`** (`Optional[MetricAggMode]`) *(optional)*: The aggregation mode for the metric. Defaults to None. Default: `None` +- **`attributes`** (`Optional[JsonDict]`) *(optional)*: Additional attributes for the metric. Defaults to None. Default: `None` + --- ##### `log_output` `log_output(...)` +Logs an output object to the task span. + +**Parameters:** + +- **`name`** (`str`): The name of the output. +- **`value`** (`t.Any`): The value of the output. +- **`label`** (`Optional[str]`) *(optional)*: An optional label for the output. Defaults to None. Default: `None` +- **`**attributes`** (`JsonValue`): Additional attributes for the output. + +**Returns:** `str` — The hash of the logged output. + --- ##### `log_param` `log_param(...)` +Logs a single parameter to the task span. + +**Parameters:** + +- **`key`** (`str`): The parameter key. +- **`value`** (`t.Any`): The parameter value. + --- ##### `log_params` `log_params(...)` +Logs multiple parameters to the task span. + +**Parameters:** + +- **`**params`** (`t.Any`): The parameters to log. + --- ##### `set_attribute` `set_attribute(...)` +Sets an attribute for the span. + +**Parameters:** + +- **`key`** (`str`): The attribute key. +- **`value`** (`t.Any`): The attribute value. +- **`schema`** (`bool`) *(optional)*: Whether to include the attribute in the schema. Defaults to True. Default: `True` +- **`raw`** (`bool`) *(optional)*: Whether to store the raw value. Defaults to False. Default: `False` + --- ##### `set_attributes` `set_attributes(...)` +Sets multiple attributes for the span. + +**Parameters:** + +- **`attributes`** (`AnyDict`): A dictionary of attributes to set. + --- @@ -643,10 +1149,30 @@ Initialize self. See help(type(self)) for accurate signature. prepare_otlp_attribute(value: Any) -> Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]] ``` +Prepares a single attribute for OTLP export. + +Converts the attribute to a format suitable for OTLP export. + +**Parameters:** + +- **`value`** (`t.Any`): The attribute value to prepare. + +**Returns:** `otel_types.AttributeValue` — The prepared attribute value. + ### `prepare_otlp_attributes` ```python prepare_otlp_attributes(attributes: dict[str, typing.Any]) -> dict[str, typing.Union[str, bool, int, float, typing.Sequence[str], typing.Sequence[bool], typing.Sequence[int], typing.Sequence[float]]] ``` +Prepares attributes for OTLP export. + +Converts attributes to a format suitable for OTLP export. + +**Parameters:** + +- **`attributes`** (`AnyDict`): A dictionary of attributes to prepare. + +**Returns:** `dict[str, otel_types.AttributeValue]` — A dictionary of prepared attributes. + diff --git a/docs/dreadnode/util.mdx b/docs/dreadnode/util.mdx index 26a5aec8..59643380 100644 --- a/docs/dreadnode/util.mdx +++ b/docs/dreadnode/util.mdx @@ -18,18 +18,46 @@ groups: ["strikes"] handle_internal_errors() -> Iterator[NoneType] ``` +A context manager to handle internal errors gracefully. + +This context manager catches exceptions raised within its block and logs +them using `log_internal_error()`. + +**Returns:** `None` — Allows the execution of the block within the context manager. + ### `log_internal_error` ```python log_internal_error() -> None ``` +Logs an internal error in the Dreadnode application. + +This function captures and logs exceptions that occur internally in the +application. If running under pytest, it may re-raise the exception +depending on the test context. + +**Raises:** + +- `Exception` — Re-raises the exception if running under pytest and the +test context allows it. + ### `safe_repr` ```python safe_repr(obj: Any) -> str ``` -Return some kind of non-empty string representation of an object, catching exceptions. +Safely generates a string representation of an object. + +This function attempts to generate a string representation of the given object +using `repr()`. If `repr()` raises an exception, it falls back to returning +a generic representation. + +**Parameters:** + +- **`obj`** (`Any`): The object to represent. + +**Returns:** `str` — A string representation of the object. From 314b3cdc503256792302998682bd4492f861d316 Mon Sep 17 00:00:00 2001 From: Brian Greunke Date: Fri, 9 May 2025 11:33:59 -0500 Subject: [PATCH 4/4] chore: linting --- dreadnode/api/client.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/dreadnode/api/client.py b/dreadnode/api/client.py index 2e8e6af8..013f374c 100644 --- a/dreadnode/api/client.py +++ b/dreadnode/api/client.py @@ -118,7 +118,8 @@ def _get_error_message(self, response: httpx.Response) -> str: try: obj = response.json() return f"{response.status_code}: {obj.get('detail', json.dumps(obj))}" - except Exception: + except Exception: # noqa: BLE001 + # BLE001: Catching Exception is generally discouraged, but here we want to catch all exceptions return str(response.content) def _request( @@ -163,7 +164,7 @@ def request( RuntimeError: If the response status code indicates an error. """ response = self._request(method, path, params, json_data) - if response.status_code == 401: + if response.status_code == 401: # noqa: PLR2004 raise RuntimeError("Authentication failed, please check your API token.") try: