Metadata-Version: 2.4
Name: teradata-agentstack
Version: 20.0.0.1
Summary: Teradata SDK for OpenAPI-based dynamic client generation
Author: Teradata Corporation
Project-URL: Homepage, http://www.teradata.com/
Keywords: Teradata,SDK,OpenAPI
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Database :: Front-Ends
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: teradataml>=20.00.00.10
Requires-Dist: requests>=2.33.0
Requires-Dist: oauthlib>=3.2.2
Requires-Dist: requests-oauthlib>=2.0.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: pandas>=0.22

# teradata-agentstack

A Python SDK package that dynamically generates client classes from OpenAPI specifications for Teradata AI/ML platform services.

It provides a unified way to work with Teradata AgentStack services from Python.

For community support, visit [Teradata Community](https://support.teradata.com/community?id=community_forum&sys_id=14fe131e1bf7f304682ca8233a4bcb1d).

For Teradata customer support, visit [Teradata Support](https://support.teradata.com/csm).

Copyright 2026 Teradata. All rights reserved.

### Table of Contents

- [Overview](#overview)
- [Release Notes](#release-notes)
- [Installation](#installation)
- [Authentication](#authentication)
- [Quick Start](#quick-start)
- [Pydantic Model Support](#pydantic-model-support)
- [Polling Async Resources](#polling-async-resources)
- [The blueprint() Function](#the-blueprint-function)
- [How Dynamic Generation Works](#how-dynamic-generation-works)
- [Notes and Limitations](#notes-and-limitations)
- [License](#license)

---

## Overview

`teradata-agentstack` provides a unified framework for interacting with Teradata platform REST APIs. Instead of hand-writing API wrappers, each SDK module reads the bundled OpenAPI JSON specification at import time and automatically creates Python classes and methods:

- **OpenAPI Tags** are converted to CamelCase Python classes.
- **Operation IDs** are converted to snake_case instance methods.
- A `blueprint()` helper lists all generated classes for a module.

### Included SDKs

| Module | Client Class | Generated Classes | Service |
|---|---|---|---|
| `teradata_agentstack.agentops` | `AgentOpsClient` | `Definitions`, `Deployments`, `Secrets`, `Health` | Teradata AgentOps |
| `teradata_agentstack.rayops` | `RayClusterManagementClient` | `RayClusterManagement`, ... | Ray Cluster Management |
| `teradata_agentstack.agento11y` | `AgentO11yClient` | `Traces`, `Projects`, `Evaluations`, ... | Agent Observability |
| `teradata_agentstack.access_manager` | `AccessManagerClient` | `Keys`, `Admin`, `Proxy` | API Access Manager |
| `teradata_agentstack.inference_engine` | `InferenceEngineClient` | `Secrets`, `Pools`, `Endpoints`, ... | Inference Engine |
| `teradata_agentstack.mcp_management` | `MCPManagementClient` | `Servers`, ... | MCP Management Service |
| `teradata_agentstack.mcp_endpoint_management` | `MCPEndpointManagementClient` | `Endpoints`, ... | MCP Endpoint Management |

---

## Release Notes

### Version 20.00.00.01

- ELE-10086 : Fixed a startup issue that could stop RayOps from loading in some environments.
- Fixed Access Manager fallback models so API responses are recognized correctly and work reliably.

### Version 20.00.00.00

- First release of `teradata-agentstack`.
- Supported SDK modules in this release:
    - `agentops`
    - `rayops`
    - `agento11y`
    - `access_manager`
    - `inference_engine`
    - `mcp_management`
    - `mcp_endpoint_management`

---

## Installation

**Version:** 20.00.00.00 | **Python:** ≥ 3.9 (64-bit) | **Platform:** Windows, macOS, Linux

```bash
pip install teradata-agentstack
```

> **Note:** A 64-bit Python environment is required. Installation will fail on 32-bit platforms.

### Dependencies

| Package | Version |
|---|---|
| `teradataml` | >=20.00.00.10 |
| `requests` | ≥ 2.33.0 |
| `oauthlib` | ≥ 3.2.2 |
| `requests-oauthlib` | ≥ 2.0.0 |
| `pydantic` | ≥ 2.10.6 |
| `PyYAML` | ≥ 6.0.2 |
| `pandas` | ≥ 0.22 |

---

## Authentication

All SDK clients accept the same authentication objects, imported from the top-level package:

```python
from teradata_agentstack import ClientCredentialsAuth, DeviceCodeAuth, BearerAuth
from teradata_agentstack._auth_modes import BasicAuth
```

### ClientCredentialsAuth — OAuth2 Client Credentials

```python
auth = ClientCredentialsAuth(
    auth_token_url="https://your-sso/token",
    auth_client_id="your_client_id",
    auth_client_secret="your_client_secret"
)
```

### DeviceCodeAuth — OAuth2 Device Code Flow

```python
auth = DeviceCodeAuth(
    auth_token_url="https://your-sso/token",
    auth_device_auth_url="https://your-sso/device_authorization",
    auth_client_id="your_client_id"
)
```

> Tokens are cached at `~/.teradataml/sdk/.token` and reused on subsequent calls.

### BearerAuth — Static Bearer Token

```python
auth = BearerAuth(auth_bearer="your_bearer_token")
```

### BasicAuth — Username / Password

```python
auth = BasicAuth(username="user", password="pass")
```

### Authentication Precedence Order

Each configuration value (`base_url`, `auth`, `ssl_verify`) is resolved in the following order. The first source that provides a value wins:

1. **Constructor arguments** — values passed directly to the client (e.g., `base_url=...`, `auth=...`).
2. **Environment variables** — values read from the process environment (e.g., `BASE_URL`, `BASE_API_AUTH_MODE`).
3. **YAML config file** — values loaded from the config file (explicit `config_file` path, or the default `~/.teradataml/sdk/config.yaml`).

> If none of the three sources supplies a required value, a `TeradataMlException` is raised.

### Authentication via Environment Variables

You can configure authentication without passing an `auth` object by setting environment variables:

| Variable | Description |
|---|---|
| `BASE_URL` | Base URL of the API endpoint |
| `BASE_API_AUTH_MODE` | `client_credentials`, `device_code`, `bearer`, or `basic` |
| `BASE_SSL_VERIFY` | `true` or `false` |
| `BASE_API_AUTH_CLIENT_ID` | OAuth2 client ID |
| `BASE_API_AUTH_CLIENT_SECRET` | OAuth2 client secret |
| `BASE_API_AUTH_TOKEN_URL` | OAuth2 token endpoint URL |
| `BASE_API_AUTH_DEVICE_AUTH_URL` | OAuth2 device authorization URL |
| `BASE_API_AUTH_BEARER_TOKEN` | Static bearer token |

### Authentication via YAML Config File

```yaml
# config.yaml
base_url: https://your-server
ssl_verify: true
auth_mode: client_credentials
auth_client_id: your_client_id
auth_client_secret: your_client_secret
auth_token_url: https://your-sso/token
```

Pass the path using the `config_file` argument on any client.

---

## Quick Start

### AgentOps SDK

```python
from teradata_agentstack import DeviceCodeAuth
from teradata_agentstack.agentops import AgentOpsClient
from teradata_agentstack.agentops import Definitions, Deployments, Secrets, Health
from teradata_agentstack.agentops.models import (
    AgentDefinitionCreateRequest,
    DeploymentCreateRequest,
)

auth = DeviceCodeAuth(
    auth_token_url="https://your-sso/token",
    auth_device_auth_url="https://your-sso/device_authorization",
    auth_client_id="your_client_id"
)

client = AgentOpsClient(
    base_url="https://your-agentops-server",
    auth=auth,
    workspace_id="your-workspace-id",
    namespace="your-k8s-namespace"
)

# Create API instances
agent_definitions = Definitions(client=client)
deployments = Deployments(client=client)
secrets = Secrets(client=client)

# Create an agent definition — pass Pydantic model directly to body=
created = agent_definitions.create(
    body=AgentDefinitionCreateRequest(
        name="my-agent",
        framework="LangGraph",
        artifacts={"storage_type": "zip"},
    ),
    file="/path/to/agent.zip",
)

# Poll until status reaches terminal state (published/failed)
agent_definitions.poll(id=created.id)

# Create a deployment
deployment = deployments.create(body=DeploymentCreateRequest(...))

# Poll until deployment is active/failed/stopped
deployments.poll(id=deployment.agent_id)
```

> **Note:** The old class names (`AgentDefinitions`, `AgentDeployments`, `AgentSecrets`) still work as backward-compatible aliases.
```

### Ray Cluster Management SDK

```python
from teradata_agentstack import ClientCredentialsAuth
from teradata_agentstack.rayops import RayClusterManagementClient

auth = ClientCredentialsAuth(
    auth_token_url="https://your-sso/token",
    auth_client_id="your_client_id",
    auth_client_secret="your_client_secret"
)

client = RayClusterManagementClient(
    base_url="https://your-ray-server",
    auth_data=auth
)
```

### Agent Observability SDK

```python
from teradata_agentstack._auth_modes import BearerAuth
from teradata_agentstack.agento11y import AgentO11yClient

auth = BearerAuth(auth_bearer="your_bearer_token")

client = AgentO11yClient(
    base_url="https://your-agento11y-server",
    auth=auth,
    project_id="your-project-id"
)
```

### Access Manager SDK

```python
from teradata_agentstack._auth_modes import BearerAuth
from teradata_agentstack.access_manager import AccessManagerClient

auth = BearerAuth(auth_bearer="your_bearer_token")

client = AccessManagerClient(
    base_url="https://your-server:9876",
    auth=auth
)
```

### Inference Engine SDK

```python
from teradata_agentstack import ClientCredentialsAuth
from teradata_agentstack.inference_engine import InferenceEngineClient

auth = ClientCredentialsAuth(
    auth_token_url="https://your-sso/token",
    auth_client_id="your_client_id",
    auth_client_secret="your_client_secret"
)

client = InferenceEngineClient(
    base_url="https://your-inference-server",
    auth=auth,
    workspace="your-workspace"
)
```

### MCP Management SDK

```python
from teradata_agentstack import ClientCredentialsAuth
from teradata_agentstack.mcp_management import MCPManagementClient

auth = ClientCredentialsAuth(
    auth_token_url="https://your-sso/token",
    auth_client_id="your_client_id",
    auth_client_secret="your_client_secret"
)

client = MCPManagementClient(
    base_url="https://your-mcp-server",
    auth=auth
)
```

### MCP Endpoint Management SDK

```python
from teradata_agentstack._auth_modes import BasicAuth
from teradata_agentstack.mcp_endpoint_management import MCPEndpointManagementClient

auth = BasicAuth(username="user", password="pass")

client = MCPEndpointManagementClient(
    base_url="https://your-mcp-server:8001",
    auth=auth
)
```

---

## Pydantic Model Support

All SDK modules support passing Pydantic models directly to request body parameters. The SDK automatically serializes models before sending:

```python
from teradata_agentstack.agentops.models import AgentDefinitionCreateRequest

# Pass Pydantic model directly — no need to call .model_dump()
result = agent_definitions.create(
    body=AgentDefinitionCreateRequest(name="my-agent", framework="LangGraph", ...),
    file="/path/to/agent.zip",
)

# Equivalent to manually serializing (still supported)
result = agent_definitions.create(
    body=AgentDefinitionCreateRequest(...).model_dump_json(by_alias=True, exclude_unset=True),
    file="/path/to/agent.zip",
)
```

---

## Polling Async Resources

Some SDK classes support a `.poll()` method for resources that are processed asynchronously:

| Module | Class | Terminal States | Success States |
|--------|-------|-----------------|----------------|
| `agentops` | `Definitions` | `published`, `failed` | `published` |
| `agentops` | `Deployments` | `active`, `failed`, `stopped` | `active` |

```python
# Poll until agent definition is published (or failed)
result = agent_definitions.poll(id=agent_def_id, interval=5, max_attempts=20)

# Poll until deployment is active (or failed/stopped)
result = deployments.poll(id=deployment_id, interval=10, max_attempts=30)
```

Parameters:
- `id` (required): Resource ID to poll
- `interval` (optional): Seconds between polls (default varies by resource)
- `max_attempts` (optional): Maximum attempts before timeout

---

## The `blueprint()` Function

Every SDK module exposes a `blueprint()` function that prints the dynamically generated classes available for that module:

```python
from teradata_agentstack.agentops import blueprint
blueprint()
# ----------------------------------------------------------------
# Available classes for AgentOps SDK:
#     * teradata_agentstack.agentops.Definitions
#     * teradata_agentstack.agentops.Deployments
#     ...
# ----------------------------------------------------------------
```

---

## How Dynamic Generation Works

When you import an SDK module (e.g., `from teradata_agentstack.agentops import AgentOpsClient`), the module:

1. Reads the bundled OpenAPI JSON specification file.
2. Converts each **tag** into a CamelCase Python class (unrecognized tags fall into `DefaultApi`).
3. Converts each **operationId** into a snake_case method on the corresponding class.
4. Validates parameters at call time — checking for required args, correct types, and permitted enum values.

All method arguments must be passed as **keyword arguments** (positional arguments are not supported).

---

## Notes and Limitations

- Only **keyword arguments** are accepted in generated API methods; positional arguments are not supported.
- Validations are performed for `string`, `integer`, `number`, `boolean`, `array`, and `object` parameter types.
- **Pydantic models** can be passed directly to `body` parameters — the SDK auto-serializes them.
- TLS certificate verification is enabled by default. Disable only in trusted development environments (`ssl_verify=False`).

---

## License

Copyright 2026 Teradata. All rights reserved. Teradata Confidential and Trade Secret.
