Metadata-Version: 2.5
Name: gatewaysdk
Version: 0.5.2
Summary: Gateway SDK for Python - tracing, worlds, evaluation and the gateway CLI runtime
Project-URL: Homepage, https://withgateway.ai
Project-URL: Documentation, https://withgateway.ai/docs
Project-URL: Repository, https://github.com/Gateway-Innovations/Gateway
Project-URL: Issues, https://github.com/Gateway-Innovations/Gateway/issues
Author-email: Gateway Team <team@withgateway.ai>
License: MIT
License-File: LICENSE
Keywords: agents,ai,evaluation,gateway,llm,observability,reinforcement-learning,training
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: aiohttp
Requires-Dist: aiologic
Requires-Dist: fastapi
Requires-Dist: flask
Requires-Dist: gitignore-parser>=0.1.11
Requires-Dist: graphviz
Requires-Dist: gunicorn
Requires-Dist: httpx>=0.24.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: openai
Requires-Dist: opentelemetry-api>=1.35
Requires-Dist: opentelemetry-exporter-otlp>=1.35
Requires-Dist: opentelemetry-sdk>=1.35
Requires-Dist: portpicker
Requires-Dist: psutil
Requires-Dist: pydantic>=2.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich
Requires-Dist: setproctitle
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn
Requires-Dist: uvicorn-worker
Provides-Extra: agent
Requires-Dist: agentops>=0.4.13; extra == 'agent'
Requires-Dist: aiohttp>=3.8.0; extra == 'agent'
Requires-Dist: typer>=0.9.0; extra == 'agent'
Provides-Extra: apo
Requires-Dist: poml; extra == 'apo'
Provides-Extra: gpu-monitoring
Requires-Dist: gpustat; extra == 'gpu-monitoring'
Provides-Extra: mongo
Requires-Dist: pymongo; extra == 'mongo'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.17; extra == 'openai-agents'
Provides-Extra: optimize
Requires-Dist: gepa>=0.0.24; extra == 'optimize'
Requires-Dist: litellm>=1.84.0; extra == 'optimize'
Provides-Extra: platform
Requires-Dist: jsonschema>=4.0.0; extra == 'platform'
Requires-Dist: pyyaml>=6.0; extra == 'platform'
Provides-Extra: proxy
Requires-Dist: litellm[proxy]>=1.84.0; extra == 'proxy'
Provides-Extra: tracing
Requires-Dist: openinference-instrumentation-anthropic; extra == 'tracing'
Requires-Dist: openinference-instrumentation-litellm; extra == 'tracing'
Requires-Dist: openinference-instrumentation-openai; extra == 'tracing'
Requires-Dist: openinference-instrumentation-openai-agents; extra == 'tracing'
Provides-Extra: trainer
Requires-Dist: litellm[proxy]>=1.84.0; extra == 'trainer'
Provides-Extra: verl
Requires-Dist: verl>=0.5.0; extra == 'verl'
Requires-Dist: vllm>=0.8.4; extra == 'verl'
Provides-Extra: weave
Requires-Dist: weave>=0.52.22; extra == 'weave'
Provides-Extra: worker
Requires-Dist: bullmq>=2.19.4; extra == 'worker'
Requires-Dist: docker>=7.0.0; extra == 'worker'
Requires-Dist: gepa>=0.0.24; extra == 'worker'
Requires-Dist: httpx>=0.24.0; extra == 'worker'
Requires-Dist: litellm>=1.84.0; extra == 'worker'
Requires-Dist: redis>=5.0.0; extra == 'worker'
Requires-Dist: typer>=0.9.0; extra == 'worker'
Description-Content-Type: text/markdown

# GatewaySDK

[![PyPI version](https://badge.fury.io/py/gatewaysdk.svg)](https://badge.fury.io/py/gatewaysdk)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**AI Agent Training and Evaluation Platform**

GatewaySDK is a comprehensive toolkit for training and evaluating AI agents using reinforcement learning, automatic prompt optimization, and supervised fine-tuning.

## Core Features

- Turn your agent into an optimizable beast with **minimal code changes**
- Build with **any** agent framework (LangChain, OpenAI Agent SDK, AutoGen, CrewAI, and more)
- **Selectively** optimize one or more agents in a multi-agent system
- Embraces **algorithms** like Reinforcement Learning, Automatic Prompt Optimization, Supervised Fine-tuning and more

## Installation

gatewaysdk 0.4.0 and later require Python 3.12 or newer (0.3.x ran on 3.10).

```bash
pip install gatewaysdk
```

Since 0.5.0 the core install leaves out `litellm` and `gepa`, so it works with any `openai`
release, including 3.x. GEPA and `LLMProxy` now need their extra; without it they raise an
`ImportError` that names the one-line fix.

For optional dependencies:

```bash
# For the GEPA prompt optimizer
pip install 'gatewaysdk[optimize]'

# For LLMProxy feature (note: has strict dependency pins for boto3, grpcio, uvicorn)
pip install 'gatewaysdk[proxy]'

# For Trainer (includes the proxy runtime it composes)
pip install 'gatewaysdk[trainer]'

# For native computer use through the OpenAI Agents SDK (AgentsComputer)
pip install 'gatewaysdk[openai-agents]'

# For GPU statistics in runner heartbeat snapshots
pip install 'gatewaysdk[gpu-monitoring]'

# For APO (Automatic Prompt Optimization)
pip install 'gatewaysdk[apo]'

# For VERL integration
pip install 'gatewaysdk[verl]'

# For Weave integration
pip install 'gatewaysdk[weave]'

# For MongoDB store
pip install 'gatewaysdk[mongo]'

# For auto-instrumentation (OpenAI, OpenAI Agents, Anthropic, LiteLLM via OpenInference)
pip install 'gatewaysdk[tracing]'
```

## Quick Start

```python
from gatewaysdk import GatewayIngestionClient

# Reads GATEWAY_HOST, GATEWAY_PUBLIC_KEY, and GATEWAY_SECRET_KEY.
client = GatewayIngestionClient.from_env()

# Your agent code here...
```

## Gateway Ingestion Helpers

Use these helpers when you want to send external agent traces/scores directly to
a Gateway instance.

### 1) Gateway ingestion client

```python
from gatewaysdk import GatewayIngestionClient, GatewayIngestionConfig

client = GatewayIngestionClient(
    GatewayIngestionConfig(
        host="http://localhost:3000",
        public_key="pk-lf-...",
        secret_key="sk-lf-...",
    )
)

# Send trace event
client.ingest_trace_event(
    trace_id="trace-001",
    name="Agent Trace",
    input_data={"prompt": "hello"},
    output_data={"answer": "world"},
    session_id="session-001",
    environment="default",
)

# Send scores efficiently in batches
client.send_scores(
    [
        {"name": "task_success", "value": 0.95, "dataType": "NUMERIC", "traceId": "trace-001"},
        {"name": "safety", "value": 1, "dataType": "BOOLEAN", "traceId": "trace-001"},
    ],
    mode="ingestion-batch",
)
```

### 2) Simple API wrapper sample (dependency-free)

For a minimal stdlib-only helper and examples, see:
`samples/gateway-agent-trace-wrapper/`.

## Security Wrapper

Use the security wrapper when Gateway should decide which native tools an
agent can see and execute. Your framework keeps owning the tools; Gateway
resolves policy, hides denied tools in filter/enforce modes, authorizes before
execution, and stamps OpenTelemetry security attributes when tracing is active.

```python
from gatewaysdk import GatewaySecurity

gw = GatewaySecurity.from_env(
    agent={
        "id": "support-triage",
        "name": "Support Triage",
        "version": "1.4.2",
    }
)

def search_tickets(query: str) -> list[dict]:
    return zendesk.search(query)

def delete_ticket(ticket_id: str) -> dict:
    return zendesk.delete(ticket_id)

tools = gw.secure_tools(
    toolset_id="zendesk",
    provider="zendesk",
    tools=[search_tickets, delete_ticket],
    context={
        "user_id": current_user.id,
        "team_id": "support",
        "environment": "production",
        "trace_id": trace_id,
        "session_id": session_id,
    },
)
```

## The `gateway` CLI

`pip install gatewaysdk` installs `gateway`, the Python twin of the npm CLI
(`npm i -g @withgateway/sdk`): the same command paths and JSON output, with the
few one-sided commands refusing by name.

```bash
export GATEWAY_HOST=https://withgateway.ai
export GATEWAY_PUBLIC_KEY=pk-lf-example
gateway auth login     # reads GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY, prompts for the rest
gateway auth status    # the credentials in effect: the environment first, then the stored file
gateway --help         # every group
```

`auth login` writes `~/.gateway/config.json`; `GATEWAY_CONFIG_DIR` moves it, and
`GATEWAY_API_KEY` is accepted in place of `GATEWAY_SECRET_KEY`. The SDK's platform
clients (`FilesClient.from_env()`, `WorldDataClient.from_env()`, world sessions,
sandboxes, connectors, environments) use the same login for any value the
environment leaves unset, but send its keys only to the host it was stored for, and
raise `CredentialsNotConfigured` when there is none. The agent-runtime clients
(personas, users, memory, context, security, tool access) read the environment only.

## The `msk` CLI

```bash
# Start the GatewaySDK server
msk store serve

# Run with vLLM
msk vllm start
```

## Documentation

For full documentation, visit [https://withgateway.ai/docs](https://withgateway.ai/docs)

## License

MIT License - see [LICENSE](LICENSE) for details.
