Metadata-Version: 2.4
Name: ntlabs
Version: 1.7.0
Summary: Python SDK for Neural Thinkers LAB AI Platform - AI Agents, OAuth v2 SSO, Document AI, Gateway Services
Project-URL: Homepage, https://www.ntlabs.dev
Project-URL: Documentation, https://www.ntlabs.dev/docs
Project-URL: Repository, https://github.com/NeuralThinkersLab/neural-lab
Author-email: Anderson Henrique da Silva <anderson@ntlabs.dev>
License: Proprietary - Neural Thinker | AI Engineering LTDA
License-File: LICENSE
Keywords: agents,ai,api,chiron,claude,dedalo,hipocrates,llm,maritaca,mercurius,neural-thinkers,ntlabs,polis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary 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: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: email-validator>=2.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: cache
Requires-Dist: redis>=5.0.0; extra == 'cache'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: email
Requires-Dist: aiosmtplib>=3.0.0; extra == 'email'
Requires-Dist: jinja2>=3.1.0; extra == 'email'
Provides-Extra: export
Requires-Dist: openpyxl>=3.1.0; extra == 'export'
Requires-Dist: pandas>=2.0.0; extra == 'export'
Requires-Dist: reportlab>=4.0.0; extra == 'export'
Provides-Extra: full
Requires-Dist: aiosmtplib>=3.0.0; extra == 'full'
Requires-Dist: fastapi>=0.100.0; extra == 'full'
Requires-Dist: jinja2>=3.1.0; extra == 'full'
Requires-Dist: openpyxl>=3.1.0; extra == 'full'
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'full'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == 'full'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.40b0; extra == 'full'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'full'
Requires-Dist: pandas>=2.0.0; extra == 'full'
Requires-Dist: redis>=5.0.0; extra == 'full'
Requires-Dist: reportlab>=4.0.0; extra == 'full'
Requires-Dist: sentry-sdk>=1.30.0; extra == 'full'
Requires-Dist: starlette>=0.27.0; extra == 'full'
Requires-Dist: supabase>=2.0.0; extra == 'full'
Provides-Extra: middleware
Requires-Dist: fastapi>=0.100.0; extra == 'middleware'
Requires-Dist: redis>=5.0.0; extra == 'middleware'
Requires-Dist: starlette>=0.27.0; extra == 'middleware'
Provides-Extra: observability
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-httpx>=0.40b0; extra == 'observability'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'observability'
Requires-Dist: sentry-sdk>=1.30.0; extra == 'observability'
Requires-Dist: supabase>=2.0.0; extra == 'observability'
Description-Content-Type: text/markdown

# Neural LAB Python SDK

**PROPRIETARY SOFTWARE - ALL RIGHTS RESERVED**

Python SDK for Neural LAB AI Platform APIs.

## Proprietary Notice

```
Copyright (c) 2026 Neural Thinker | AI Engineering LTDA
CNPJ: 62.155.930/0001-71
Author: Anderson Henrique da Silva
Location: Minas Gerais, Brasil

This software is proprietary and confidential.
Unauthorized copying, distribution, or use is strictly prohibited.
```

## Installation

```bash
pip install ntlabs
```

### Optional Dependencies

```bash
# Full installation with all features
pip install ntlabs[full]

# Specific features
pip install ntlabs[cache]        # Redis caching
pip install ntlabs[email]        # Email templates
pip install ntlabs[export]       # PDF/Excel export
pip install ntlabs[middleware]   # FastAPI middleware
pip install ntlabs[observability] # Sentry + OpenTelemetry
```

### For Local Development

```bash
pip install -e /path/to/neural-lab/packages/python-sdk[dev]
```

## Quick Start

```python
from neural_lab import NeuralLabClient

# Initialize client
client = NeuralLabClient(api_key="nl_hipo_xxx")

# Or use environment variable NEURAL_LAB_API_KEY
client = NeuralLabClient()
```

## Available Resources

### Chat (LLM)

```python
response = client.chat.complete(
    messages=[
        {"role": "system", "content": "Você é um assistente médico."},
        {"role": "user", "content": "O que é hipertensão?"}
    ],
    model="maritaca-sabia-4",
    max_tokens=1024,
)
```

### Email

```python
client.email.send(
    to=["paciente@email.com"],
    subject="Confirmação de Consulta",
    html="<h1>Sua consulta foi agendada</h1>",
)
```

### Transcription

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

### Government APIs

```python
# CNPJ lookup
empresa = client.gov.cnpj("12.345.678/0001-90")

# CEP lookup
endereco = client.gov.cep("01310-100")

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

# Portal da Transparência
contratos = client.gov.transparencia("contratos", params={"uf": "MG"})
```

### Banco do Brasil (OAuth + PIX)

```python
from decimal import Decimal

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

# OAuth - 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}")

# PIX - Create charge
charge = client.bb.create_pix_charge(
    amount=Decimal("99.90"),
    description="Consulta Médica",
)
print(f"QR Code: {charge.qr_code}")

# PIX - Check status
status = client.bb.get_pix_status(charge.txid)
if status.status == "CONCLUIDA":
    print(f"Pago em: {status.paid_at}")
```

### Medical AI (Hipócrates)

```python
# Transcribe consultation
transcription = client.saude.transcribe(audio_file)

# Generate SOAP note
soap = client.saude.generate_soap(
    transcription=transcription.text,
    paciente={"idade": 45, "sexo": "M"},
)
```

### Notary AI (Mercurius)

```python
# OCR certificate
result = client.cartorio.ocr(image_file, tipo="nascimento")

# Generate deed
minuta = client.cartorio.generate_escritura(dados)
```

### Billing

```python
usage = client.billing.get_usage()
print(f"Total: R$ {usage.total_cost}")
```

### Authentication (OAuth v2 with PKCE)

```python
# Initiate OAuth flow (returns URL for redirect)
oauth = client.auth.initiate_oauth_v2(
    provider="github",  # or "google"
    redirect_uri="https://myapp.com/auth/callback",
    product="hipocrates",
)
# Redirect user to: oauth["authorization_url"]

# After callback, claim the session (frontend receives sid + sig in URL)
session = client.auth.claim_session(
    session_id="sess_xxx",
    signature="hmac_xxx",
)
print(f"Token: {session['access_token']}")
print(f"User: {session['user']['email']}")

# Validate a session
validation = client.auth.validate_session(
    session_id="sess_xxx",
    product="hipocrates",
)
if validation["valid"]:
    print(f"User: {validation['user']['email']}")

# Check SSO (for cross-product auth)
sso = client.auth.check_sso(product="mercurius")
if sso["has_valid_session"]:
    print("User already authenticated via SSO")

# Refresh tokens (with rotation)
new_tokens = client.auth.refresh_v2(
    refresh_token="old_refresh_token",
    session_id="sess_xxx",
)

# Logout (single session)
client.auth.revoke_session(session_id="sess_xxx")

# Global logout (all sessions)
client.auth.revoke_session(revoke_all=True)
```

### SSO Cross-Product Navigation

```python
# Create ticket for navigating to another product
ticket = client.auth.create_sso_ticket(target_product="mercurius")
# Redirect to: https://mercurius.app/auth?sso_ticket={ticket['ticket']}

# On target product: exchange ticket for session
session = client.auth.exchange_sso_ticket(
    ticket="ticket_xxx",
    target_product="mercurius",
)
```

## Environment Variables

| Variable             | Description                                     |
| -------------------- | ----------------------------------------------- |
| `NEURAL_LAB_API_KEY` | API key (nl_hipo_xxx, nl_merc_xxx, nl_poli_xxx) |
| `NEURAL_LAB_API_URL` | API URL (default: production)                   |

## 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")
except APIError as e:
    print(f"API error: {e}")
```

### AI Agents

```python
from ntlabs import NTLClient

client = NTLClient(api_key="ntl_xxx")

# List available agents
agents = client.agents.list()
for agent in agents:
    print(f"{agent.name}: {agent.description_pt}")

# Chat with an agent
response = client.agents.chat(
    agent="dedalo",  # dedalo, chiron, themis, hermes, athena
    messages=[{"role": "user", "content": "Olá!"}],
    session_id="session_123",
)
print(response.message)

# Streaming chat
for chunk in client.agents.chat_stream(
    agent="dedalo",
    messages=[{"role": "user", "content": "Conte-me sobre a Neural LAB"}],
):
    if chunk.type == "token":
        print(chunk.content, end="", flush=True)
```

**Available Agents:**

| Agent    | Product    | Description                | Status      |
| -------- | ---------- | -------------------------- | ----------- |
| `dedalo` | Neural LAB | Sales & Lead Qualification | Active      |
| `chiron` | Hipócrates | Medical AI Assistant       | Beta        |
| `themis` | Argos      | Legal AI Assistant         | Coming Soon |
| `hermes` | Mercúrius  | Notary AI Assistant        | Coming Soon |
| `athena` | Pólis      | Public Health AI Assistant | Coming Soon |

## Publishing to PyPI

### Automatic (GitHub Actions)

Create a release with tag `sdk-v{version}`:

```bash
gh release create sdk-v1.4.0 \
  --repo NeuralThinkersLab/neural-lab \
  --title "ntlabs v1.4.0 - Release Title" \
  --notes "Release notes..."
```

### Manual (when GitHub Actions billing is unavailable)

```bash
cd packages/python-sdk

# Build
python -m venv venv
./venv/bin/pip install build twine
./venv/bin/python -m build

# Publish (token from ~/.env)
source ~/.env
TWINE_USERNAME=__token__ TWINE_PASSWORD=$PYPI_TOKEN ./venv/bin/twine upload dist/ntlabs-{version}*
```

## License

**Proprietary Software**

Copyright (c) 2026 Neural Thinker | AI Engineering LTDA

All rights reserved. This software and its documentation are proprietary
and confidential. No part of this software may be reproduced, distributed,
or transmitted in any form or by any means without the prior written
permission of Neural Thinker | AI Engineering LTDA.

For licensing inquiries: contato@ntlabs.dev
