Metadata-Version: 2.4
Name: solvela-sdk
Version: 0.1.2
Summary: Solana-native payment gateway for AI agents — pay for LLM calls with USDC, no API keys
Project-URL: Homepage, https://solvela.ai
Project-URL: Repository, https://github.com/solvela-ai/solvela-python
Project-URL: Issues, https://github.com/solvela-ai/solvela-python/issues
Author-email: Solvela <dev@solvela.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,payment-gateway,solana,usdc,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: mnemonic<1.0,>=0.20
Requires-Dist: solders<0.30,>=0.21
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# solvela

Python SDK for [Solvela](https://github.com/solvela-ai/solvela) — a Solana-native AI agent payment gateway. AI agents pay for LLM API calls with USDC-SPL on Solana via the x402 protocol.

## Installation

```bash
pip install solvela-sdk
```

For development:

```bash
pip install -e ".[dev]"
```

## Quick Start

```python
import asyncio
from solvela import SolvelaClient, ClientConfig, Wallet

async def main():
    wallet, mnemonic = Wallet.create()
    print(f"Wallet: {wallet.address()}")
    print(f"Mnemonic (save this!): {mnemonic}")

    config = ClientConfig(gateway_url="http://localhost:8402")
    client = SolvelaClient(config=config, wallet=wallet)

    # List available models
    models = await client.models()
    for m in models:
        print(f"  {m.id} — {m.display_name}")

    # Estimate cost (triggers 402)
    cost = await client.estimate_cost("gpt-4o")
    print(f"Cost: {cost.cost_breakdown.total} {cost.cost_breakdown.currency}")

asyncio.run(main())
```

## OpenAI-Compatible Interface

```python
from solvela import SolvelaClient
from solvela.openai_compat import OpenAICompat

client = SolvelaClient()
openai = OpenAICompat(client)

# Same interface as the OpenAI Python SDK
response = await openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

## Smart Features

- **Response caching** — `enable_cache=True` deduplicates identical requests
- **Session tracking** — `enable_sessions=True` tracks conversation context with three-strike escalation
- **Quality checks** — `enable_quality_check=True` detects degraded responses and retries
- **Balance guard** — automatic fallback to free models when USDC balance hits zero
- **Balance monitor** — background polling with low-balance callbacks

## Configuration

```python
from solvela import ClientConfig, ClientBuilder

# Dataclass
config = ClientConfig(
    gateway_url="http://localhost:8402",
    enable_cache=True,
    enable_sessions=True,
    enable_quality_check=True,
    free_fallback_model="deepseek-chat",
    max_payment_amount=100_000,  # atomic USDC (0.10 USDC)
)

# Fluent builder
config = (
    ClientBuilder()
    .gateway_url("http://localhost:8402")
    .enable_cache(True)
    .max_payment_amount(100_000)
    .build()
)
```

## Running Tests

```bash
# Unit + integration tests
pytest tests/unit/ tests/integration/ -v

# Live contract tests (requires running gateway)
SOLVELA_LIVE_TESTS=1 pytest tests/live/ -v

# Linting
ruff check src/ tests/
```

## License

MIT
