# aphub-sdk

Python SDK for aphub - The Docker Hub for AI Agents

## Installation

```bash
pip install aphub-sdk
```

## Quick Start

### Basic Usage

```python
from aphub_sdk import HubClient
from pathlib import Path

# Initialize client
client = HubClient(
    base_url="https://hub.aipartnerup.com",
    api_key="your-api-key"  # Optional, can use token instead
)

# Pull an Agent
result = client.pull(
    name="customer-service-agent",
    tag="latest",
    output_path=Path("./agents")
)

# Push an Agent
result = client.push(
    manifest=Path("./agent.yaml"),
    tag="latest",
    files_path=Path("./agent-files/")
)

# Search Agents
results = client.search(
    query="customer service",
    framework="aipartnerupflow",
    page_size=20
)

# Get Agent details
agent = client.get_agent("customer-service-agent")

# List tags
tags = client.list_tags("customer-service-agent")
```

## Use Cases

### 1. CI/CD Pipeline Integration

Automatically deploy agents after successful builds:

```python
import os
from aphub_sdk import HubClient

def deploy_in_cicd():
    client = HubClient(api_key=os.environ["APHUB_API_KEY"])
    result = client.push(
        manifest=Path("./dist/agent.yaml"),
        tag=os.environ.get("VERSION", "latest"),
        files_path=Path("./dist/agent-files"),
    )
    print(f"Deployed: {result.name}:{result.version}")
```

### 2. Custom Web Application

Build custom UIs and backends:

```python
from fastapi import FastAPI
from aphub_sdk import HubClient

app = FastAPI()
client = HubClient()

@app.get("/api/agents")
def list_agents():
    result = client.search(query="", page_size=50)
    return {"agents": [item.agent.name for item in result.results]}
```

### 3. Agent Management Scripts

Batch operations and automation:

```python
client = HubClient(api_key="your-key")

# Bulk operations
for agent_name in ["agent1", "agent2", "agent3"]:
    client.pull(agent_name, output_path=Path(f"./backups/{agent_name}"))
```

### 4. Agent Testing and Validation

Validate agents before pushing:

```python
def validate_and_push(manifest_path, files_path):
    # Your validation logic here
    if validate_agent(manifest_path, files_path):
        return client.push(manifest_path, files_path=files_path)
    else:
        raise ValueError("Validation failed")
```

## Advanced Features

### Retry Configuration

```python
from aphub_sdk import HubClient
from aphub_sdk.retry import RetryConfig

client = HubClient(
    retry_config=RetryConfig(
        max_retries=5,
        backoff_factor=2.0,
    )
)
```

### Token Auto-Refresh

```python
client = HubClient(
    access_token="your-access-token",
    refresh_token="your-refresh-token",
)
# Tokens automatically refreshed when expired
```

### Progress Tracking

```python
def progress(bytes_sent, total_bytes):
    print(f"Progress: {bytes_sent}/{total_bytes}")

client = HubClient(progress_callback=progress)
client.pull("my-agent", output_path=Path("./agents"))
```

## When to Use SDK vs CLI

| Use Case | SDK | CLI |
|----------|-----|-----|
| CI/CD Pipelines | ✅ | ❌ |
| Custom Applications | ✅ | ❌ |
| Scripts/Automation | ✅ | ⚠️ |
| Interactive Use | ⚠️ | ✅ |
| Batch Operations | ✅ | ❌ |

## Documentation

- [Usage Scenarios](USAGE_SCENARIOS.md) - Detailed use cases and examples
- [API Reference](docs/api.md) - Complete API documentation
- [Examples](examples/) - Code examples

## License

Apache-2.0

