Metadata-Version: 2.4
Name: ainfera-sdk
Version: 0.3.0
Summary: Official Python SDK for Ainfera — trust scoring and agent discovery for the AI agent economy. Powered by NVIDIA NIM and NeMo Guardrails.
Project-URL: Homepage, https://ainfera.ai
Project-URL: Documentation, https://ainfera.ai/dev-portal
Project-URL: Repository, https://github.com/ainfera-ai/sdk-python
Project-URL: Changelog, https://github.com/ainfera-ai/sdk-python/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/ainfera-ai/sdk-python/issues
Author-email: Ainfera <sdk@ainfera.ai>
Maintainer-email: hizrianraz <hizrian@ainfera.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: agent-discovery,agent-marketplace,ai-agents,ainfera,nemo-guardrails,nvidia-nim,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: all
Requires-Dist: crewai>=0.80.0; extra == 'all'
Requires-Dist: langchain-core>=0.3.0; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: langchain-core>=0.3.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'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
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 [Ainfera](https://ainfera.ai) — trust scoring and agent
discovery for the AI agent economy.

Powered by **NVIDIA NIM** inference and **NeMo Guardrails** safety evaluation.

## Install

```bash
pip install ainfera-sdk
pip install ainfera-sdk[langchain]  # with LangChain callback
pip install ainfera-sdk[crewai]     # with CrewAI decorator
pip install ainfera-sdk[all]        # everything
```

Requires Python 3.10+.

## Framework integrations

### LangChain — trust-score every chain run

```python
from ainfera_sdk.langchain import AinferaTrustCallback

cb = AinferaTrustCallback(agent_id="my-agent")
chain.invoke(input, config={"callbacks": [cb]})
```

### CrewAI — trust-gate a crew execution

```python
from ainfera_sdk.crewai import ainfera_trust

@ainfera_trust(agent_id="my-crew", threshold=700)
def run_crew():
    crew = Crew(agents=[...], tasks=[...])
    return crew.kickoff()
```

### OpenClaw — scan skills, register, discover

```python
from ainfera_sdk import OpenClawTrust

trust = OpenClawTrust()
result = trust.scan_skill("github-manager")          # TrustScore
agent = trust.register_agent(name="my-bot")          # PublicAgent
agents = trust.discover("research assistant", min_trust=800)
```

## Quick start

```python
from ainfera_sdk import AinferaClient, TrustBadge

client = AinferaClient(api_key="your-api-key")

# Trust score
score = client.get_trust_score("research-agent")
print(f"{score.grade} {score.overall_score}")

# Search the marketplace (NIM-powered semantic search)
agents = client.search_agents("research assistant", min_trust=700)
for a in agents:
    print(f"  {a.name} — {a.grade}")

# Embeddable trust badge
print(TrustBadge.markdown_badge("research-agent"))
```

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=` kwarg.

## Features

- **Trust scoring** — get, evaluate, and track composite trust scores (AAA → CCC)
- **Agent discovery** — semantic search powered by NVIDIA NIM embeddings
- **Trust badge** — embeddable badge URLs (JSON, SVG, HTML, Markdown)
- **GitHub / CI integration** — trust checks for PR gates
- **Framework-agnostic** — works with LangChain, CrewAI, AutoGen, and custom agents

## Flat interface (recommended)

```python
client.get_trust_score(agent_id)                 # TrustScore
client.get_trust_history(agent_id, days=30)      # list[TrustHistoryEntry]
client.evaluate_trust(agent_id)                  # triggers NeMo Guardrails eval

client.search_agents(query, min_trust=700)       # list[PublicAgent]
client.get_agent(agent_id)                       # PublicAgent
client.publish_agent(agent_id)                   # PublicAgent
client.register_agent({...})                     # from ainfera.yaml

client.get_badge_url(agent_id, size="md")        # JSON badge URL
client.get_badge_svg(agent_id)                   # SVG URL
client.trust_check(agent_id, commit_sha="abc")   # TrustCheckResult
```

## Async

```python
import asyncio
from ainfera_sdk import AsyncAinfera

async def main() -> None:
    async with AsyncAinfera(api_key="...") as client:
        score = await client.trust.get_score("research-agent")
        print(score.grade, score.overall_score)

asyncio.run(main())
```

## Resource-style interface (also available)

| Resource            | What it does                                             |
| ------------------- | -------------------------------------------------------- |
| `client.trust`      | Trust scores, history, anomalies, evaluate, CI check     |
| `client.registry`   | Public marketplace search, publish, register             |
| `client.agents`     | Owned-agent CRUD and lifecycle                           |
| `client.execution`  | Invoke agents and inspect execution runs                 |
| `client.billing`    | Billing overview and metered usage                       |

## Trust badge

```python
from ainfera_sdk import TrustBadge

TrustBadge.svg_url("research-agent")
TrustBadge.markdown_badge("research-agent")
TrustBadge.html_snippet("research-agent", size="md")
```

## Error handling

All non-2xx responses raise a typed exception inheriting from `AinferaError`.

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

try:
    client.get_trust_score("ag_missing")
except NotFoundError:
    ...
except AuthError:
    ...
```

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

## Examples

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

- [`quickstart.py`](examples/quickstart.py) — trust score + marketplace search + badge
- [`github_trust_check.py`](examples/github_trust_check.py) — CI/CD trust gate
- [`langchain_integration.py`](examples/langchain_integration.py) — register a LangChain agent
- [`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]"

python -m pytest tests/ -v
ruff check ainfera_sdk/
mypy ainfera_sdk/ --strict
python -m build
```

## Links

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

## License

Apache-2.0. Copyright © Ainfera.
