# Gibs Python SDK

Official Python SDK for the [Gibs](https://gibs.dev) multi-regulation compliance API. Classify AI system risk levels, check regulatory obligations, and get answers to compliance questions -- all with source citations to EU legislation (AI Act, GDPR, DORA).

## Installation

```bash
pip install gibs
```

## Quick Start

```python
from gibs import GibsClient

client = GibsClient(api_key="gbs_live_xxx")

# Classify an AI system's risk level
result = client.classify("Facial recognition system for airport security")
print(result.risk_level)   # "high"
print(result.confidence)   # 0.92
print(result.reasoning)    # Detailed explanation with article references
print(result.sources)      # [SourceCitation(article_id="Article 6", ...)]

# Ask a compliance question (auto-detects regulation)
answer = client.check("What are the transparency obligations for chatbots?")
print(answer.answer)
print(answer.sources)      # [SourceCitation(article_id="Article 50", ...)]

# DORA: ICT resilience for financial entities
dora = client.check("What are the ICT incident reporting timelines under DORA?")
print(dora.answer)         # Timeline with Article 19 citations
```

## Async Support

```python
from gibs import AsyncGibsClient

client = AsyncGibsClient(api_key="gbs_live_xxx")

result = await client.classify("CV screening tool for recruitment")
answer = await client.check("Does GDPR apply to employee monitoring?")

# Use as async context manager
async with AsyncGibsClient(api_key="gbs_live_xxx") as client:
    result = await client.classify("...")
```

## Authentication

Get your API key at [gibs.dev](https://gibs.dev). Pass it directly or set the `GIBS_API_KEY` environment variable:

```bash
export GIBS_API_KEY=gbs_live_xxx
```

```python
# Reads from GIBS_API_KEY automatically
client = GibsClient()
```

## API Reference

### `client.classify(description, **kwargs)`

Classify an AI system's risk level under EU regulation.

```python
result = client.classify(
    "Emotion detection system for job interviews",
    data_types=["biometric", "behavioral"],
    decision_scope="employment",
    sector="recruitment",
    jurisdiction="EU",
)

print(result.risk_level)      # "prohibited" | "high" | "limited" | "minimal"
print(result.confidence)      # 0.0 - 1.0
print(result.reasoning)       # Detailed explanation
print(result.obligations)     # List of compliance obligations
print(result.sources)         # Source citations to legislation
print(result.corpus_version)  # Version of the legal corpus used
```

### `client.check(question, **kwargs)`

Ask a compliance question and get an answer with citations. The API automatically detects which regulation(s) the question targets (AI Act, GDPR, DORA) and routes to the correct corpus.

```python
answer = client.check(
    "What data protection impact assessment is required for high-risk AI?",
    system_context={"type": "recommendation engine", "sector": "healthcare"},
)

print(answer.answer)            # Detailed answer
print(answer.confidence)        # "high" | "medium" | "low"
print(answer.sources)           # Source citations
print(answer.should_abstain)    # True if out of scope
print(answer.corpus_version)    # Corpus version used
```

### `client.health()`

Check API health status.

```python
health = client.health()
print(health.status)       # "healthy"
print(health.components)   # {"qdrant": "ok", "postgres": "ok", ...}
```

### Account Management

```python
# List API keys
keys = client.list_keys()

# Create a new key
new_key = client.create_key("CI Pipeline")
print(new_key.api_key)  # Full key shown once

# Revoke a key
client.delete_key(key_id=2)
```

## Error Handling

```python
from gibs import GibsClient, GibsAuthError, GibsRateLimitError, GibsAPIError

client = GibsClient(api_key="gbs_live_xxx")

try:
    result = client.classify("...")
except GibsAuthError:
    print("Invalid API key")
except GibsRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except GibsAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
```

The SDK automatically retries on rate limits and transient network errors with exponential backoff (3 retries by default).

## Configuration

```python
client = GibsClient(
    api_key="gbs_live_xxx",          # Required (or set GIBS_API_KEY env var)
    base_url="https://api.gibs.dev", # Default
    timeout=120.0,                    # Seconds (default: 120)
    max_retries=3,                    # Retry count (default: 3)
)
```

## Requirements

- Python 3.10+
- [httpx](https://www.python-httpx.org/)
- [pydantic](https://docs.pydantic.dev/) v2

## Links

- [Documentation](https://docs.gibs.dev)
- [API Reference](https://docs.gibs.dev/api)
- [Website](https://gibs.dev)
