appserver-sdk-python-ai 0.0.3

SDK Python para serviços de IA da AppServer com suporte a contagem de tokens

AppServer SDK Python AI

SDK Python para integração com serviços de IA da AppServer.

🚀 Características

• Cliente HTTP assíncrono e síncrono
• Modelos Pydantic para validação de dados
• Retry automático com backoff exponencial
• Type hints completos
• Suporte a múltiplos provedores de IA
• Logging estruturado
• Testes abrangentes

📦 Instalação

Via Poetry (Recomendado)

poetry add appserver-sdk-python-ai

Via pip

pip install appserver-sdk-python-ai

Via GitHub (Desenvolvimento)

# Via Poetry
poetry add git+https://github.com/appserver/appserver-sdk-python-ai.git

# Via pip
pip install git+https://github.com/appserver/appserver-sdk-python-ai.git

🔧 Uso Básico

Cliente Síncrono

from appserver_sdk_python_ai import AIClient
from appserver_sdk_python_ai.models import AIRequest

# Configurar cliente
client = AIClient(
    base_url="https://api.appserver.com.br/ai/v1",
    api_key="sua-api-key"
)

# Fazer requisição
request = AIRequest(
    prompt="Explique machine learning em termos simples",
    model="gpt-4",
    max_tokens=500
)

response = client.chat_completion(request)
print(response.content)

Cliente Assíncrono

import asyncio
from appserver_sdk_python_ai import AsyncAIClient

async def main():
    client = AsyncAIClient(
        base_url="https://api.appserver.com.br/ai/v1",
        api_key="sua-api-key"
    )
    
    request = AIRequest(
        prompt="O que é inteligência artificial?",
        model="gpt-3.5-turbo"
    )
    
    response = await client.chat_completion(request)
    print(response.content)
    
    await client.close()

asyncio.run(main())

Configuração Avançada

from appserver_sdk_python_ai import AIClient, AIConfig

config = AIConfig(
    base_url="https://api.appserver.com.br/ai/v1",
    api_key="sua-api-key",
    timeout=30,
    max_retries=3,
    retry_delay=1.0,
    debug=True
)

client = AIClient(config=config)

🛠️ Desenvolvimento

Pré-requisitos

• Python 3.11+
• Poetry

Configuração do Ambiente

# Clonar repositório
git clone https://github.com/appserver/appserver-sdk-python-ai.git
cd appserver-sdk-python-ai

# Instalar dependências
poetry install

# Configurar pre-commit hooks
poetry run pre-commit install

# Ativar ambiente virtual
poetry shell

Executar Testes

# Todos os testes
poetry run pytest

# Com cobertura
poetry run pytest --cov=appserver_sdk_python_ai --cov-report=html

# Apenas testes unitários
poetry run pytest -m unit

# Apenas testes de integração
poetry run pytest -m integration

Linting e Formatação

# Verificar e corrigir código
poetry run ruff check . --fix
poetry run ruff format .

# Verificar tipos
poetry run mypy src/

# Verificar segurança
poetry run bandit -r src/
poetry run safety check

Executar Exemplo

# Exemplo básico
poetry run python examples/basic_usage.py

# Exemplo assíncrono
poetry run python examples/async_usage.py

📚 Documentação

Estrutura do Projeto

appserver-sdk-python-ai/
├── src/
│   └── appserver_sdk_python_ai/
│       ├── __init__.py
│       ├── client/
│       │   ├── sync_client.py
│       │   └── async_client.py
│       ├── models/
│       │   ├── request_models.py
│       │   ├── response_models.py
│       │   └── config_models.py
│       ├── exceptions/
│       │   └── ai_exceptions.py
│       └── utils/
│           ├── retry.py
│           └── logging.py
├── tests/
├── examples/
├── docs/
└── pyproject.toml

Modelos Disponíveis

• AIRequest: Modelo de requisição
• AIResponse: Modelo de resposta
• AIConfig: Configuração do cliente
• AIError: Modelo de erro

Exceções

• AIException: Exceção base
• AIConnectionError: Erro de conexão
• AIAuthenticationError: Erro de autenticação
• AIRateLimitError: Erro de limite de taxa
• AITimeoutError: Erro de timeout

🤝 Contribuindo

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

Padrões de Commit

Seguimos o padrão Conventional Commits:

• feat: nova funcionalidade
• fix: correção de bug
• docs: mudanças na documentação
• style: formatação de código
• refactor: refatoração de código
• test: adição ou correção de testes
• chore: tarefas de manutenção

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🆘 Suporte

• Email: [e-mail]
• Issues: GitHub Issues
• Documentação: Wiki

📊 Status do Projeto

• ✅ Cliente básico implementado
• ✅ Modelos Pydantic
• ✅ Testes unitários
• 🔄 Documentação (em andamento)
• 🔄 Testes de integração (em andamento)
• ⏳ Suporte a streaming (planejado)
• ⏳ Cache de respostas (planejado)

---

Desenvolvido com ❤️ pela equipe AppServer