appserver-sdk-python-ai 0.0.16

SDK Python para serviços de IA da AppServer

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

📦 Módulos Disponíveis

🤖 LLM (Large Language Models)

Módulo profissional para integração com modelos de linguagem e APIs de inteligência artificial.

Características principais:

• Cliente assíncrono e síncrono
• Retry automático com backoff exponencial
• Suporte a múltiplos provedores de IA
• Modelos Pydantic com type hints completos
• Sistema de logging estruturado
• Gerenciamento seguro de API keys

📖 Documentação completa do LLM

🔍 WebScraping

Módulo profissional de web scraping com conversão para markdown usando Docling.

Características principais:

• Scraping robusto com retry automático
• Conversão de alta qualidade usando Docling (IBM)
• Processamento paralelo de múltiplas URLs
• Sistema de cache inteligente
• Limpeza automática de conteúdo
• Extração de metadados ricos
• OCR integrado: Processamento de imagens e PDFs
• Múltiplos engines: Tesseract, EasyOCR, PaddleOCR

📖 Documentação completa do WebScraping

👁️ OCR (Optical Character Recognition)

Módulo especializado para extração de texto de imagens e documentos.

Características principais:

• Múltiplos engines de OCR (Tesseract, EasyOCR, PaddleOCR)
• Seleção automática do melhor engine disponível
• Formatos suportados: JPEG, PNG, GIF, TIFF, BMP, WEBP
• Pré-processamento automático de imagens
• Cache inteligente de resultados
• Processamento em lote paralelo
• Suporte a múltiplos idiomas
• Integração com processamento de PDFs

📖 Documentação completa do OCR

📦 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

Módulo WebScraping

from appserver_sdk_python_ai.webscraping import quick_scrape

# Scraping simples
markdown = quick_scrape("https://example.com")
print(markdown)

Módulo OCR

from appserver_sdk_python_ai.ocr import quick_ocr

# OCR simples de uma imagem
texto = quick_ocr("documento.png")
print(texto)

# OCR com configurações específicas
from appserver_sdk_python_ai.ocr import OCRProcessor, OCRConfig

config = OCRConfig(
    languages=["por", "eng"],
    engine="tesseract"
)

processor = OCRProcessor(config)
resultado = processor.process_image("imagem.jpg")
print(resultado.text)
print(f"Confiança: {resultado.confidence}%")

Módulo LLM - 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)

Módulo LLM - 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())

Módulo LLM - 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

Documentação dos Módulos

• LLM - Guia completo do módulo de modelos de linguagem
• WebScraping - Guia completo do módulo de web scraping
• OCR - Guia completo do módulo de reconhecimento óptico de caracteres

Estrutura do Projeto

appserver-sdk-python-ai/
├── src/
│   └── appserver_sdk_python_ai/
│       ├── __init__.py
│       ├── llm/                    # Módulo LLM
│       │   ├── __init__.py
│       │   ├── README.md           # Documentação do LLM
│       │   ├── core/
│       │   ├── service/
│       │   └── exceptions/
│       ├── webscraping/            # Módulo WebScraping
│       │   ├── __init__.py
│       │   ├── README.md           # Documentação do WebScraping
│       │   ├── core/
│       │   ├── docling/
│       │   ├── utils/
│       │   └── tests/
│       ├── ocr/                    # Módulo OCR
│       │   ├── __init__.py
│       │   ├── README.md           # Documentação do OCR
│       │   ├── core/
│       │   ├── engines/
│       │   └── utils/
│       └── shared/                 # Utilitários compartilhados
│           ├── __init__.py
│           └── exceptions.py
├── tests/
├── scripts/
└── 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