Metadata-Version: 2.3
Name: appserver-sdk-python-ai
Version: 0.0.17
Summary: SDK Python para serviços de IA da AppServer
License: MIT
Keywords: ai,tokens,llm,openai,huggingface,sdk,tokenizer
Author: AppServer Team
Author-email: suporte@appserver.com.br
Maintainer: AppServer Team
Maintainer-email: suporte@appserver.com.br
Requires-Python: >=3.11
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Provides-Extra: analysis
Provides-Extra: dev
Provides-Extra: full
Provides-Extra: huggingface
Provides-Extra: llm
Provides-Extra: local-models
Provides-Extra: openai
Requires-Dist: httpx (>=0.24.0,<1.0.0) ; extra == "full"
Requires-Dist: httpx (>=0.24.0,<1.0.0) ; extra == "llm"
Requires-Dist: llama-cpp-python (>=0.2.0,<1.0.0) ; extra == "local-models"
Requires-Dist: matplotlib (>=3.5.0,<4.0.0) ; extra == "analysis"
Requires-Dist: mypy (>=1.8.0) ; extra == "dev"
Requires-Dist: nltk (>=3.8,<4.0.0) ; extra == "analysis"
Requires-Dist: onnxruntime (>=1.12.0,<2.0.0) ; extra == "local-models"
Requires-Dist: pandas (>=1.5.0,<3.0.0) ; extra == "analysis"
Requires-Dist: pre-commit (>=3.6.0) ; extra == "dev"
Requires-Dist: psutil (>=5.9.0,<6.0.0) ; extra == "full"
Requires-Dist: psutil (>=5.9.0,<6.0.0) ; extra == "llm"
Requires-Dist: pydantic (>=2.0.0,<3.0.0) ; extra == "full"
Requires-Dist: pydantic (>=2.0.0,<3.0.0) ; extra == "llm"
Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.23.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=4.0.0) ; extra == "dev"
Requires-Dist: ruff (>=0.12.7) ; extra == "dev"
Requires-Dist: seaborn (>=0.11.0,<1.0.0) ; extra == "analysis"
Requires-Dist: spacy (>=3.4.0,<4.0.0) ; extra == "analysis"
Requires-Dist: structlog (>=23.0.0,<25.0.0) ; extra == "full"
Requires-Dist: structlog (>=23.0.0,<25.0.0) ; extra == "llm"
Requires-Dist: textblob (>=0.17.0,<1.0.0) ; extra == "analysis"
Requires-Dist: tiktoken (>=0.5.0,<1.0.0) ; extra == "full"
Requires-Dist: tiktoken (>=0.5.0,<1.0.0) ; extra == "openai"
Requires-Dist: torch (>=1.12.0,<3.0.0) ; extra == "local-models"
Requires-Dist: torch (>=2.2.2,<3.0.0) ; extra == "full"
Requires-Dist: torch (>=2.2.2,<3.0.0) ; extra == "huggingface"
Requires-Dist: transformers (>=4.20.0,<5.0.0) ; extra == "local-models"
Requires-Dist: transformers (>=4.30.0,<5.0.0) ; extra == "full"
Requires-Dist: transformers (>=4.30.0,<5.0.0) ; extra == "huggingface"
Requires-Dist: types-requests (>=2.31.0) ; extra == "dev"
Requires-Dist: typing-extensions (>=4.0.0,<5.0.0) ; extra == "full"
Requires-Dist: typing-extensions (>=4.0.0,<5.0.0) ; extra == "llm"
Project-URL: Documentation, https://appserver.com.br/docs
Project-URL: Homepage, https://appserver.com.br
Description-Content-Type: text/markdown

# AppServer SDK Python AI

[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

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](src/appserver_sdk_python_ai/llm/README.md)**

### 🔍 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](src/appserver_sdk_python_ai/webscraping/README.md)**

### 👁️ 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](src/appserver_sdk_python_ai/ocr/README.md)**

## 📦 Instalação

### Via Poetry (Recomendado)
```bash
poetry add appserver-sdk-python-ai
```

### Via pip
```bash
pip install appserver-sdk-python-ai
```

### Via GitHub (Desenvolvimento)
```bash
# 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

```python
from appserver_sdk_python_ai.webscraping import quick_scrape

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

### Módulo OCR

```python
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

```python
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

```python
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

```python
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Exemplos básicos
poetry run python examples/basic_usage.py
poetry run python examples/async_usage.py

# Exemplos do módulo LLM
poetry run python examples/llm/custom_model_example.py
poetry run python examples/llm/metrics_example.py

# Demonstrações completas do módulo LLM
poetry run python examples/llm/features_demo.py
poetry run python examples/llm/improvements_demo.py
poetry run python examples/llm/medium_priority_demo.py
```

## 📚 Documentação

### Documentação dos Módulos

- **[LLM](src/appserver_sdk_python_ai/llm/README.md)** - Guia completo do módulo de modelos de linguagem
- **[WebScraping](src/appserver_sdk_python_ai/webscraping/README.md)** - Guia completo do módulo de web scraping
- **[OCR](src/appserver_sdk_python_ai/ocr/README.md)** - 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/
├── examples/                       # Exemplos de uso e demonstrações
├── 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

## 🤖 Módulo LLM

O módulo LLM oferece funcionalidades avançadas para interação com modelos de linguagem:

### 🚀 Funcionalidades Principais

- **Cliente LLM**: Interface unificada para diferentes provedores
- **Cache Inteligente**: Sistema de cache LRU thread-safe para otimização
- **Validação Robusta**: Validação de entrada e saída com múltiplos níveis
- **Logging Estruturado**: Sistema de logging avançado com contexto
- **Métricas e Monitoramento**: Coleta automática de métricas de performance
- **Configuração Centralizada**: Gerenciamento unificado de configurações

### 📊 Sistema de Métricas

O módulo inclui um sistema abrangente de métricas:

```python
from appserver_sdk_python_ai.llm import (
    get_metrics_summary,
    export_metrics,
    record_operation_metric
)

# Coleta automática durante operações
summary = get_metrics_summary()
print(f"Operações realizadas: {len(summary['operation_stats'])}")

# Exportação para análise
export_metrics(format_type="json", file_path="metrics.json")
export_metrics(format_type="prometheus", file_path="metrics.prom")
```

**Tipos de Métricas Coletadas:**
- ⏱️ Latência e duração de operações
- 📈 Contadores de sucesso/erro
- 💾 Uso de memória e CPU
- 🔢 Estatísticas de tokens processados
- 📊 Histogramas de performance

### 📖 Documentação Completa

Para documentação detalhada do módulo LLM, consulte:
- **[📚 README do Módulo LLM](src/appserver_sdk_python_ai/llm/README.md)** - Documentação completa e consolidada
- **[🔧 Documentação Interativa](src/appserver_sdk_python_ai/llm/docs/interactive_docs.py)** - Acesso dinâmico à documentação
- **[💡 Exemplos Práticos](examples/llm/)** - Exemplos de uso organizados por funcionalidade
- **[📊 Métricas e Outputs](output/metrics/)** - Arquivos de métricas e relatórios
- **[📝 Logs do Sistema](logs/)** - Logs estruturados da aplicação

> **Nota**: A documentação do módulo LLM foi consolidada em um único local para evitar redundância. O sistema de documentação interativa carrega dinamicamente o conteúdo do README.md do módulo.

## 🤝 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](https://www.conventionalcommits.org/):

- `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

### Convenções de Documentação

#### Nomenclatura de Arquivos
- **Preferência**: Documentação no `README.md` do próprio módulo
- **Formato alternativo**: `{modulo}-{tipo}.md` (apenas quando necessário)

#### Estrutura dos Documentos
1. **Título e Descrição**
2. **Índice** (se necessário)
3. **Conteúdo Principal**
4. **Exemplos Práticos**
5. **Referências e Links**

#### Adicionando Nova Documentação
1. **Criar Arquivo**: Use a convenção `{modulo}-{tipo}.md`
2. **Seguir Estrutura**: Mantenha consistência com documentos existentes
3. **Atualizar README**: Adicione referência neste arquivo
4. **Links Cruzados**: Atualize links relevantes em outros documentos

#### Manutenção da Documentação
- **Revisão Regular**: Mensal ou a cada release
- **Verificações**: Links funcionais, informações atualizadas, exemplos válidos
- **Sincronização**: Manter sincronizado com mudanças no código
- **Versionamento**: Indicar mudanças significativas

## 📄 Licença

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

## 🆘 Suporte

- **Email**: suporte@appserver.com.br
- **Issues**: [GitHub Issues](https://github.com/appserver/appserver-sdk-python-ai/issues)
- **Documentação**: [Wiki](https://github.com/appserver/appserver-sdk-python-ai/wiki)

## 📊 Status do Projeto

- ✅ Cliente básico implementado
- ✅ Modelos Pydantic
- ✅ Testes unitários
- ✅ Módulo LLM com funcionalidades avançadas
- ✅ Sistema de métricas e monitoramento
- ✅ Cache LRU thread-safe
- ✅ Validação robusta de dados
- ✅ Logging estruturado
- ✅ Configuração centralizada
- 🔄 Documentação (em andamento)
- 🔄 Testes de integração (em andamento)
- ⏳ Suporte a streaming (planejado)

---

**Desenvolvido com ❤️ pela equipe AppServer**

