Skip to content

Commit

Permalink
Update chains docs (#1227)
Browse files Browse the repository at this point in the history 
* Update Chains Docs

* Update Chains Docs 2

* Fixups
  • Loading branch information
@marius-baseten
marius-baseten authored Nov 4, 2024
1 parent 0ec34a7 commit fc0ecf9
Show file tree
Hide file tree
Showing 5 changed files with 228 additions and 115 deletions.
98 changes: 56 additions & 42 deletions docs/chains/doc_gen/API-reference.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,11 @@ chainlet instance is provided.

**Parameters:**

| Name | Type | Description |
|----------------|----------------------|--------------------------------------------------------------------------------------------------------------|
| `chainlet_cls` | *Type[ChainletBase]* | The chainlet class of the dependency. |
| `retries` | *int* | The number of times to retry the remote chainlet in case of failures (e.g. due to transient network issues). |
| `timeout_sec` | *int* | Timeout for the HTTP request to this chainlet. |
| Name | Type | Description |
|----------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| `chainlet_cls` | *Type[[ChainletBase](#class-truss-chains-chainletbase)]* | The chainlet class of the dependency. |
| `retries` | *int* | The number of times to retry the remote chainlet in case of failures (e.g. due to transient network issues). |
| `timeout_sec` | *int* | Timeout for the HTTP request to this chainlet. |
* **Returns:**
A “symbolic marker” to be used as a default argument in a chainlet’s
initializer.
Expand All @@ -65,7 +65,7 @@ context instance is provided.
A “symbolic marker” to be used as a default argument in a chainlet’s
initializer.

### *class* `truss_chains.DeploymentContext(Generic[UserConfigT])`
### *class* `truss_chains.DeploymentContext`

Bases: `pydantic.BaseModel`

Expand All @@ -85,11 +85,7 @@ an access token for downloading model weights).
| `chainlet_to_service` | *Mapping[str,[ServiceDescriptor](#class-truss-chains-servicedescriptor)]* | A mapping from chainlet names to service descriptors. This is used create RPCs sessions to dependency chainlets. It contains only the chainlet services that are dependencies of the current chainlet. |
| `secrets` | *Mapping[str,str]* | A mapping from secret names to secret values. It contains only the secrets that are listed in `remote_config.assets.secret_keys` of the current chainlet. |
| `user_env` | *Mapping[str,str]* | These values can be provided to the deploy command and customize the behavior of deployed chainlets. E.g. for differentiating between prod and dev version of the same chain. |

#### chainlet_to_service:
Mapping[str, [ServiceDescriptor](#class-truss-chains-servicedescriptor)]*

#### data_dir *: Path | None*
| `environment` | *[Environment](#class-truss-chains-definitions-environment)\|None* | The environment that the chainlet is deployed in. None if the chainlet is not associated with an environment. |

#### get_baseten_api_key()

Expand All @@ -107,11 +103,26 @@ Mapping[str, [ServiceDescriptor](#class-truss-chains-servicedescriptor)]*
* **Return type:**
[*ServiceDescriptor*](#class-truss-chains-servicedescriptor)

#### secrets *: Mapping[str, str]*
### *class* `truss_chains.definitions.Environment`

Bases: `pydantic.BaseModel`

The environment the chainlet is deployed in.

* **Parameters:**
**name** (*str*) – The name of the environment.

#### user_config *: UserConfigT*
### *class* `truss_chains.ChainletOptions`

#### user_env *: Mapping[str, str]*
Bases: `pydantic.BaseModel`


**Parameters:**

| Name | Type | Description |
|------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `enable_b10_tracing` | *bool* | enables baseten-internal trace data collection. This helps baseten engineers better analyze chain performance in case of issues. It is independent of a potentially user-configured tracing instrumentation. Turning this on, could add performance overhead. |
| `env_variables` | *Mapping[str,str]* | static environment variables available to the deployed chainlet. |

### *class* `truss_chains.RPCOptions`

Expand Down Expand Up @@ -147,9 +158,9 @@ class MyChainlet(ChainletBase):

**Parameters:**

| Name | Type | Description |
|-------|----------------------|---------------------|
| `cls` | *Type[ChainletBase]* | The chainlet class. |
| Name | Type | Description |
|-------|----------------------------------------------------------|---------------------|
| `cls` | *Type[[ChainletBase](#class-truss-chains-chainletbase)]* | The chainlet class. |

* **Return type:**
*Type*[*ChainletBase*]
Expand Down Expand Up @@ -182,12 +193,13 @@ class MyChainlet(chains.ChainletBase):

**Parameters:**

| Name | Type | Description |
|----------------|--------------------------------------------------|-------------|
| `docker_image` | *[DockerImage](#class-truss-chains-dockerimage)* | |
| `compute` | *[Compute](#class-truss-chains-compute)* | |
| `assets` | *[Assets](#class-truss-chains-assets)* | |
| `name` | *str\|None* | |
| Name | Type | Description |
|----------------|----------------------------------------------------------|-------------|
| `docker_image` | *[DockerImage](#class-truss-chains-dockerimage)* | |
| `compute` | *[Compute](#class-truss-chains-compute)* | |
| `assets` | *[Assets](#class-truss-chains-assets)* | |
| `name` | *str\|None* | |
| `options` | *[ChainletOptions](#class-truss-chains-chainletoptions)* | |

### *class* `truss_chains.DockerImage`

Expand Down Expand Up @@ -220,11 +232,12 @@ Bases: `Enum`
Default images, curated by baseten, for different python versions. If a Chainlet
uses GPUs, drivers will be included in the image.

#### PY310 *= 'py310'*

#### PY311 *= 'py311'*
| Enum Member | Value |
|-------------|---------|
| `PY310` | *py310* |
| `PY311 ` | *py311* |
| `PY39` | *py39* |

#### PY39 *= 'py39'*

### *class* `truss_chains.CustomImage`

Expand Down Expand Up @@ -312,15 +325,16 @@ Deploys a chain remotely (with all dependent chainlets).

**Parameters:**

| Name | Type | Description |
|-------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `entrypoint` | *Type[ChainletBase]* | The chainlet class that serves as the entrypoint to the chain. |
| `chain_name` | *str* | The name of the chain. |
| `publish` | *bool* | Whether to publish the chain as a published deployment (it is a draft deployment otherwise) |
| `promote` | *bool* | Whether to promote the chain to be the production deployment (this implies publishing as well). |
| `user_env` | *Mapping[str,str]\|None* | These values can be provided to the push command and customize the behavior of deployed chainlets. E.g. for differentiating between prod and dev version of the same chain. |
| `only_generate_trusses` | *bool* | Used for debugging purposes. If set to True, only the the underlying truss models for the chainlets are generated in `/tmp/.chains_generated`. |
| `remote` | *str\|None* | name of a remote config in .trussrc. If not provided, it will be inquired. |
| Name | Type | Description |
|-------------------------|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `entrypoint` | *Type[[ChainletBase](#class-truss-chains-chainletbase)]* | The chainlet class that serves as the entrypoint to the chain. |
| `chain_name` | *str* | The name of the chain. |
| `publish` | *bool* | Whether to publish the chain as a published deployment (it is a draft deployment otherwise) |
| `promote` | *bool* | Whether to promote the chain to be the production deployment (this implies publishing as well). |
| `user_env` | *Mapping[str,str]\|None* | These values can be provided to the push command and customize the behavior of deployed chainlets. E.g. for differentiating between prod and dev version of the same chain. |
| `only_generate_trusses` | *bool* | Used for debugging purposes. If set to True, only the the underlying truss models for the chainlets are generated in `/tmp/.chains_generated`. |
| `remote` | *str\|None* | name of a remote config in .trussrc. If not provided, it will be inquired. |
| `environment` | *str\|None* | The name of an environment to promote deployment into. |

* **Returns:**
A chain service handle to the deployed chain.
Expand Down Expand Up @@ -442,7 +456,7 @@ Context manager local debug execution of a chain.

The arguments only need to be provided if the chainlets explicitly access any the
corresponding fields of
[`DeploymentContext`](#class-truss-chains-deploymentcontext-generic-userconfigt).
[`DeploymentContext`](#class-truss-chains-deploymentcontext).

**Parameters:**

Expand Down Expand Up @@ -552,11 +566,11 @@ Factory method, convenient to be used in chainlet’s `__init__`-method.

**Parameters:**

| Name | Type | Description |
|---------------|----------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `predict_url` | *str* | URL to predict endpoint of another chain / truss model. |
| `context` | *[DeploymentContext](#class-truss-chains-deploymentcontext-generic-userconfigt)* | Deployment context object, obtained in the chainlet’s `__init__`. |
| `options` | *[RPCOptions](#class-truss-chains-rpcoptions)* | RPC options, e.g. retries. |
| Name | Type | Description |
|---------------|--------------------------------------------------------------|-------------------------------------------------------------------|
| `predict_url` | *str* | URL to predict endpoint of another chain / truss model. |
| `context` | *[DeploymentContext](#class-truss-chains-deploymentcontext)* | Deployment context object, obtained in the chainlet’s `__init__`. |
| `options` | *[RPCOptions](#class-truss-chains-rpcoptions)* | RPC options, e.g. retries. |

### *class* `truss_chains.RemoteErrorDetail`

Expand Down
3 changes: 3 additions & 0 deletions docs/chains/doc_gen/generate_reference.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
# "truss_chains.definitions.AssetSpec",
# "truss_chains.definitions.ComputeSpec",
"truss_chains.remote.ChainService",
"truss_chains.definitions.Environment",
]


Expand All @@ -42,6 +43,8 @@
"truss_chains.depends",
"truss_chains.depends_context",
"truss_chains.DeploymentContext",
"truss_chains.definitions.Environment",
"truss_chains.ChainletOptions",
"truss_chains.RPCOptions",
"truss_chains.mark_entrypoint",
],
Expand Down
36 changes: 34 additions & 2 deletions docs/chains/doc_gen/generated-reference.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,11 +89,14 @@ an access token for downloading model weights).
| `chainlet_to_service` | *Mapping[str,[ServiceDescriptor](#truss_chains.ServiceDescriptor* | A mapping from chainlet names to service descriptors. This is used create RPCs sessions to dependency chainlets. It contains only the chainlet services that are dependencies of the current chainlet. |
| `secrets` | *MappingNoIter[str,str]* | A mapping from secret names to secret values. It contains only the secrets that are listed in `remote_config.assets.secret_keys` of the current chainlet. |
| `user_env` | *Mapping[str,str]* | These values can be provided to the deploy command and customize the behavior of deployed chainlets. E.g. for differentiating between prod and dev version of the same chain. |
| `environment` | *[Environment](#truss_chains.definitions.Environment* | The environment that the chainlet is deployed in. None if the chainlet is not associated with an environment. |

#### chainlet_to_service *: Mapping[str, [ServiceDescriptor](#truss_chains.ServiceDescriptor)]*

#### data_dir *: Path | None*

#### environment *: [Environment](#truss_chains.definitions.Environment) | None*

#### get_baseten_api_key()

* **Return type:**
Expand All @@ -112,6 +115,32 @@ an access token for downloading model weights).

#### user_env *: Mapping[str, str]*

### *class* `truss_chains.definitions.Environment`

Bases: `pydantic.BaseModel`

The environment the chainlet is deployed in.

* **Parameters:**
**name** (*str*) – The name of the environment.
#### name *: str*

### *class* `truss_chains.ChainletOptions`

Bases: `pydantic.BaseModel`


**Parameters:**

| Name | Type | Description |
|------|------|-------------|
| `enable_b10_tracing` | *bool* | enables baseten-internal trace data collection. This helps baseten engineers better analyze chain performance in case of issues. It is independent of a potentially user-configured tracing instrumentation. Turning this on, could add performance overhead. |
| `env_variables` | *Mapping[str,str]* | static environment variables available to the deployed chainlet. |

#### enable_b10_tracing *: bool*

#### env_variables *: Mapping[str, str]*

### *class* `truss_chains.RPCOptions`

Bases: `pydantic.BaseModel`
Expand Down Expand Up @@ -187,6 +216,7 @@ class MyChainlet(chains.ChainletBase):
| `compute` | *[Compute](#truss_chains.Compute* | |
| `assets` | *[Assets](#truss_chains.Assets* | |
| `name` | *str\|None* | |
| `options` | *[ChainletOptions](#truss_chains.ChainletOptions* | |


#### assets *: [Assets](#truss_chains.Assets)*
Expand All @@ -207,6 +237,8 @@ class MyChainlet(chains.ChainletBase):

#### name *: str | None*

#### options *: [ChainletOptions](#truss_chains.ChainletOptions)*

### *class* `truss_chains.DockerImage`

Bases: `pydantic.BaseModel`
Expand Down Expand Up @@ -377,6 +409,7 @@ Deploys a chain remotely (with all dependent chainlets).
| `user_env` | *Mapping[str,str]\|None* | These values can be provided to the push command and customize the behavior of deployed chainlets. E.g. for differentiating between prod and dev version of the same chain. |
| `only_generate_trusses` | *bool* | Used for debugging purposes. If set to True, only the the underlying truss models for the chainlets are generated in `/tmp/.chains_generated`. |
| `remote` | *str\|None* | name of a remote config in .trussrc. If not provided, it will be inquired. |
| `environment` | *str\|None* | The name of an environment to promote deployment into. |

* **Returns:**
A chain service handle to the deployed chain.
Expand Down Expand Up @@ -435,8 +468,7 @@ This property must be externally populated.
Queries the statuses of all chainlets in the chain.

* **Returns:**
List of `DeployedChainlet`, `(name, is_entrypoint, status, logs_url)`
for each chainlet.
List of `DeployedChainlet` for each chainlet.
* **Return type:**
list[*DeployedChainlet*]

Expand Down
Loading

0 comments on commit fc0ecf9

Please sign in to comment.