neural-lab-sdk 0.6.1
Python SDK for Neural LAB AI Platform - LLM, Email, Transcription, Gov APIs
License: MIT
Requires Python: >=3.10
Keywords: ai, api, brazil, claude, llm, maritaca, neural-lab, openai, transcription

# Neural LAB Python SDK

[![PyPI version](https://badge.fury.io/py/neural-lab-sdk.svg)](https://pypi.org/project/neural-lab-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

Python SDK for **Neural LAB AI Platform** - Unified API for LLM, Email, Transcription, and Brazilian Government services.

## Installation

```bash
pip install neural-lab-sdk
```

## Quick Start

```python
from neural_lab import NeuralLabClient

# Initialize with API key
client = NeuralLabClient(api_key="nl_xxx")

# Or use environment variable NEURAL_LAB_API_KEY
client = NeuralLabClient()

# Chat with LLM
response = client.chat.complete(
    messages=[{"role": "user", "content": "Olá!"}],
    model="maritaca-sabia-3"
)
print(response.choices[0].message.content)

# Don't forget to close
client.close()
```

### Async Usage

```python
from neural_lab import AsyncNeuralLabClient

async with AsyncNeuralLabClient(api_key="nl_xxx") as client:
    response = await client.chat.complete(messages=[...])
    empresa = await client.gov.cnpj("12.345.678/0001-90")
```

## Available Resources

| Resource | Description |
|----------|-------------|
| `client.chat` | LLM completions (Maritaca, Claude, GPT) |
| `client.email` | Email sending via Resend |
| `client.transcribe` | Audio transcription (Deepgram, Groq Whisper) |
| `client.gov` | Government APIs (CNPJ, CPF, CEP) |
| `client.ibge` | IBGE geographic/demographic data |
| `client.bb` | Banco do Brasil OAuth + PIX |
| `client.saude` | Medical AI (Hipócrates) |
| `client.cartorio` | Notary AI (Mercurius) |
| `client.billing` | Usage and subscription |

## Examples

### Chat (LLM)

```python
response = client.chat.complete(
    messages=[
        {"role": "system", "content": "Você é um assistente útil."},
        {"role": "user", "content": "O que é machine learning?"}
    ],
    model="maritaca-sabia-3",
    max_tokens=1024,
)
print(response.choices[0].message.content)
```

### Email

```python
client.email.send(
    to=["user@example.com"],
    subject="Bem-vindo!",
    html="<h1>Obrigado por se cadastrar</h1>",
)
```

### Transcription

```python
result = client.transcribe.audio("audio.mp3", language="pt")
print(result.text)
```

### Government APIs

```python
# CNPJ lookup
empresa = client.gov.cnpj("12.345.678/0001-90")
print(f"{empresa.razao_social} - {empresa.situacao}")

# CEP lookup
endereco = client.gov.cep("01310-100")
print(f"{endereco.logradouro}, {endereco.cidade}/{endereco.uf}")

# CPF validation
valido = client.gov.validate_cpf("123.456.789-00")
```

### IBGE Data

```python
# List states
estados = client.ibge.estados()

# Municipalities by state
municipios = client.ibge.municipios("MG")

# Population estimate
pop = client.ibge.populacao(3106200)  # Belo Horizonte
print(f"População: {pop.populacao:,}")

# GDP per capita
pib = client.ibge.pib(3106200)
print(f"PIB per capita: R$ {pib.pib_per_capita:,.2f}")
```

### Banco do Brasil (OAuth + PIX)

```python
from decimal import Decimal

# OAuth flow
auth = client.bb.get_authorize_url(redirect_uri="https://app.com/callback")
# Redirect user to auth.authorize_url

# Exchange code for tokens
tokens = client.bb.exchange_code(code="abc", state="xyz", redirect_uri="...")

# Get user info (CPF verified by bank)
user = client.bb.get_userinfo(tokens.access_token)
print(f"CPF: {user.cpf}, Nome: {user.nome}")

# Create PIX charge
charge = client.bb.create_pix_charge(
    amount=Decimal("99.90"),
    description="Pagamento",
)
print(f"QR Code: {charge.qr_code}")
```

## Error Handling

```python
from neural_lab import (
    NeuralLabClient,
    AuthenticationError,
    RateLimitError,
    InsufficientCreditsError,
    APIError,
)

try:
    response = client.chat.complete(messages=[...])
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except InsufficientCreditsError:
    print("Add more credits at https://neural-lab.com.br")
except APIError as e:
    print(f"API error: {e}")
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `NEURAL_LAB_API_KEY` | Your API key |
| `NEURAL_LAB_API_URL` | Custom API URL (optional) |

## Requirements

- Python 3.10+
- httpx >= 0.25.0

## Links

- **API Reference**: https://neural-lab-production.up.railway.app/docs

## License

MIT License - see [LICENSE](LICENSE) for details.

---

**Made with ❤️ in Minas Gerais, Brasil**