Metadata-Version: 2.4
Name: ainfera-sdk
Version: 0.1.0
Summary: Python SDK for the Ainfera AI agent infrastructure platform
Project-URL: Homepage, https://ainfera.ai
Project-URL: Repository, https://github.com/ainfera-ai/sdk-python
Project-URL: Issues, https://github.com/ainfera-ai/sdk-python/issues
Author-email: Ainfera <sdk@ainfera.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,ainfera,infrastructure,trust-scoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; 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.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# ainfera-sdk

[![PyPI](https://img.shields.io/pypi/v/ainfera-sdk.svg)](https://pypi.org/project/ainfera-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/ainfera-sdk.svg)](https://pypi.org/project/ainfera-sdk/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Official Python SDK for the [Ainfera](https://ainfera.ai) AI agent infrastructure platform — deploy, monitor, and trust-score AI agents from any framework (LangChain, LlamaIndex, AutoGen, CrewAI, and more).

## Install

```bash
pip install ainfera-sdk
```

Requires Python 3.10+.

## Quickstart

```python
from ainfera_sdk import Ainfera

client = Ainfera(api_key="ainf_sk_live_...")

# List your agents
for agent in client.agents.list():
    print(agent.id, agent.name, agent.status)

# Deploy a new agent
agent = client.agents.create(
    name="research-assistant",
    framework="langchain",
    compute_tier="standard",
)

# Fetch its composite trust score
score = client.trust.get_score(agent.id)
print(f"{score.overall_score} ({score.grade})")
```

The SDK reads `AINFERA_API_KEY` from the environment if no key is passed. The base URL can be overridden with `AINFERA_API_URL` or the `base_url=` constructor argument.

## Async

```python
import asyncio
from ainfera_sdk import AsyncAinfera

async def main() -> None:
    async with AsyncAinfera(api_key="ainf_sk_live_...") as client:
        agents = await client.agents.list()
        score = await client.trust.get_score(agents[0].id)
        print(score.overall_score)

asyncio.run(main())
```

## Resources

The client exposes five sub-resources:

| Resource          | What it does                                             |
| ----------------- | -------------------------------------------------------- |
| `client.agents`   | Deploy, list, update, kill, and delete agents            |
| `client.trust`    | Read trust scores, history, anomalies, and record events |
| `client.billing`  | Inspect billing overview and metered usage               |
| `client.execution`| Invoke agents and inspect execution runs                 |
| `client.registry` | Search the public agent registry (no auth required)      |

### Agents

```python
client.agents.list(page=1, per_page=20)          # list[Agent]
client.agents.get(agent_id)                      # Agent
client.agents.create(name=..., framework=...)    # Agent
client.agents.update(agent_id, name="renamed")   # Agent
client.agents.kill(agent_id)                     # emergency stop
client.agents.unkill(agent_id)                   # resume
client.agents.delete(agent_id)                   # permanent delete
```

### Trust

```python
client.trust.get_score(agent_id)        # TrustScore
client.trust.get_history(agent_id)      # list[TrustHistoryEntry]
client.trust.get_anomalies(agent_id)    # list[Anomaly]
client.trust.record_event(agent_id, event_type="hallucination", data={...})
client.trust.recompute(agent_id)        # TrustScore (forced recompute)
client.trust.badge_url(agent_id)        # str (embed as SVG)
```

### Execution

```python
run = client.execution.invoke(agent_id, input={"query": "..."})
client.execution.get_run(run.id)
client.execution.list_runs(agent_id, limit=20)
```

### Registry (no auth required)

```python
from ainfera_sdk import Ainfera

public = Ainfera(api_key=None)  # registry endpoints are public
public.registry.search(q="research", framework="langchain")
public.registry.get(agent_id)
public.registry.stats()
```

### Billing

```python
client.billing.overview()                              # BillingOverview
client.billing.usage(start="2026-04-01", end="2026-04-30")
```

## Error handling

All non-2xx responses raise a typed exception. Every SDK exception inherits from `AinferaError` and exposes `.status_code`, `.message`, and `.response_body`.

```python
from ainfera_sdk import AuthError, NotFoundError, RateLimitError, ServerError

try:
    client.agents.get("ag_missing")
except NotFoundError:
    ...
except AuthError:
    ...
except RateLimitError:
    ...
except ServerError:
    ...
```

| Exception         | HTTP status |
| ----------------- | ----------- |
| `AuthError`       | 401, 403    |
| `ValidationError` | 400, 422    |
| `NotFoundError`   | 404         |
| `RateLimitError`  | 429         |
| `ServerError`     | 5xx         |
| `ApiError`        | anything else non-2xx |

## Examples

See the [`examples/`](examples/) directory:

- [`quickstart.py`](examples/quickstart.py) — list agents and fetch a trust score
- [`deploy_langchain.py`](examples/deploy_langchain.py) — deploy a LangChain agent and invoke it
- [`trust_monitoring.py`](examples/trust_monitoring.py) — pull trust history and record events

## Development

```bash
git clone https://github.com/ainfera-ai/sdk-python.git
cd sdk-python
pip install -e ".[dev]"

# Tests (HTTP-mocked, no real API calls)
python -m pytest tests/ -v

# Lint + type check
ruff check ainfera_sdk/ --fix
ruff format ainfera_sdk/
mypy ainfera_sdk/ --strict
```

## Links

- Homepage: https://ainfera.ai
- API docs: https://api.ainfera.ai/docs
- Issues: https://github.com/ainfera-ai/sdk-python/issues

## License

Apache-2.0. Copyright © Ainfera Pte. Ltd.
