🤖 Create Agents AI

🎯 Sobre

Create Agents AI é um framework Python modular e extensível para construção de agentes conversacionais inteligentes, seguindo os princípios de Clean Architecture e SOLID. Projetado para ambientes enterprise, oferece suporte a múltiplos provedores de IA (OpenAI, Ollama), ferramentas extensíveis e métricas integradas.

Por que usar?

• ✅ Arquitetura Limpa: Código testável, manutenível e escalável
• ✅ Múltiplos Provedores: OpenAI e Ollama (local/privado)
• ✅ Ferramentas Extensíveis: Sistema de tools com suporte a customização
• ✅ Histórico Contextual: Gerenciamento automático de conversas
• ✅ Métricas Integradas: Monitoramento em JSON e Prometheus
• ✅ Type Safety: Suporte completo a type hints
• ✅ CI/CD Profissional: Quality checks automáticos com GitHub Actions

✨ Features

🤖 Provedores de IA

🔧 Ferramentas Built-in

📊 Recursos Avançados

• Histórico Automático: Gerenciamento de contexto conversacional
• Métricas de Performance: Exportação em JSON e Prometheus
• Sanitização de Logs: Proteção automática de dados sensíveis
• Logging Configurável: Silencioso por padrão, ativável para debug
• Ferramentas Customizadas: Interface BaseTool para extensões
• Configuração Flexível: Temperature, max_tokens, top_p, think mode e mais.

📝 Logging

A biblioteca é silenciosa por padrão (não emite logs). Para ver logs durante o desenvolvimento:

import logging
from createagents import LoggingConfig

# Ativar logs para debug
LoggingConfig.configure_for_development(level=logging.INFO)

📖 Guia completo de Logging

🚀 Instalação Rápida

Pré-requisitos

• Python 3.12 ou superior
• pip (geralmente incluído com Python)

Instalação via PyPI (Usuários)

# Instalação básica
pip install createagents

# OU com suporte a leitura de arquivos (PDF, Excel, CSV, Parquet)
pip install createagents[file-tools]

Configuração

# Configure sua chave de API da OpenAI
export OPENAI_API_KEY="sk-proj-sua-chave"

# Ou crie um arquivo .env no seu projeto
echo "OPENAI_API_KEY=sk-proj-sua-chave" > .env

Instalação para Desenvolvimento (Contribuidores)

Se você deseja contribuir com o projeto:

# Clone o repositório
git clone https://github.com/jor0105/Create-Agents-AI.git
cd Create-Agents-AI

# Instale com Poetry
poetry install

# OU com suporte a file-tools
poetry install -E file-tools

# Configure o ambiente
cp .env.example .env
# Edite .env e adicione: OPENAI_API_KEY=sk-proj-sua-chave

📖 Guia completo para contribuidores →

💡 Quick Start

Exemplo Básico

from createagents import CreateAgent

# Criar agente
agent = CreateAgent(
    provider="openai",
    model="gpt-4",
    instructions="Você é um assistente técnico especializado em Python"
)

# Conversar
response = agent.chat("Como criar uma função recursiva?")
print(response)

Com Ferramentas

from createagents import CreateAgent

# Agente com ferramentas
agent = CreateAgent(
    provider="openai",
    model="gpt-4",
    tools=["currentdate", "readlocalfile"]
)

# O agente usa ferramentas automaticamente
agent.chat("Que dia é hoje?")  # Usa CurrentDateTool
agent.chat("Leia o arquivo report.pdf")  # Usa ReadLocalFileTool

Ollama (Local)

# Instalar Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Baixar modelo
ollama pull llama3.2:latest
ollama serve

# Usar modelo local
agent = CreateAgent(
    provider="ollama",
    model="llama3.2",
    instructions="Você é um assistente local"
)

response = agent.chat("Explique Clean Architecture")
print(response)

📋 Exemplos de Uso

Exemplo 1: Assistente de Programação

from createagents import CreateAgent

assistant = CreateAgent(
    provider="openai",
    model="gpt-4",
    name="Code Assistant",
    instructions="Você é um especialista em programação Python. Sempre forneça exemplos de código.",
    config={"temperature": 0.3}  # Menos criatividade para código
)

# Conversar
response = assistant.chat("Como ordenar uma lista de dicionários por chave?")
print(response)

# Ver histórico
config = assistant.get_configs()
print(f"Histórico: {len(config['history'])} mensagens")

# Limpar e começar novo diálogo
assistant.clear_history()

Exemplo 2: Múltiplos Agentes

# Um para análise
analyzer = CreateAgent(
    provider="openai",
    model="gpt-4",
    instructions="Você analisa código e fornece feedback crítico",
    config={"temperature": 0.5}
)

# Outro para documentação
documentor = CreateAgent(
    provider="openai",
    model="gpt-4",
    instructions="Você escreve documentação clara e profissional",
    config={"temperature": 0.3}
)

# Usar ambos
code = "def sum(a,b): return a+b"
feedback = analyzer.chat(f"Revise este código:\n{code}")
docs = documentor.chat(f"Documente este código:\n{code}")

print("Feedback:", feedback)
print("Documentação:", docs)

Exemplo 3: Ferramenta Customizada

from createagents import CreateAgent, BaseTool

class CalculatorTool(BaseTool):
    name = "calculator"
    description = "Realiza cálculos matemáticos"
    parameters = {
        "type": "object",
        "properties": {
            "expression": {"type": "string", "description": "Expressão matemática"}
        },
        "required": ["expression"]
    }

    def execute(self, expression: str) -> str:
        return str(eval(expression))

# Criar agente com ferramenta customizada
agent = CreateAgent(
    provider="openai",
    model="gpt-4",
    tools=["currentdate", CalculatorTool()]
)

# Ver todas as ferramentas
all_tools = agent.get_all_available_tools()
print(f"Total de ferramentas: {len(all_tools)}")
for name, description in all_tools.items():
    print(f"  • {name}: {description[:50]}...")

Exemplo 4: Métricas e Performance

# Ver métricas de chamadas
metrics = agent.get_metrics()

# Exportar como JSON
json_data = agent.export_metrics_json()

# Exportar formato Prometheus
prom_data = agent.export_metrics_prometheus()

# Salvar em arquivo
agent.export_metrics_json("metrics.json")
agent.export_metrics_prometheus("metrics.prom")

🏗️ Arquitetura

Este projeto segue Clean Architecture e SOLID Principles:

src/
└─ createagents/                # Pacote principal
    ├─ domain/                 # Regras de negócio (entidades, services, value_objects, exceptions)
    ├─ application/            # Casos de uso e DTOs (lógica da aplicação)
    ├─ infra/                  # Implementações externas (adapters, factories, config)
    ├─ main/                   # Composição e injeção de dependências (composers)
    └─ utils/                  # Utilitários (text_sanitizer, helpers)

Diagrama de Camadas

┌─────────────────────────────────────┐
│        PRESENTATION                 │  ← CreateAgent (interface simples)
│     (Controllers/UI)                │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│        APPLICATION                  │  ← Use Cases & DTOs
│    (Business Logic)                 │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│          DOMAIN                     │  ← Entities & Rules
│    (Core Business)                  │
└──────────────▲──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│      INFRASTRUCTURE                 │  ← Adapters (OpenAI, Ollama)
│  (External Services)                │
└─────────────────────────────────────┘

Benefícios: Testável, Flexível, Escalável e Manutenível

📖 Documentação completa da arquitetura

📚 Documentação

Guia do Usuário

• 📖 Instalação
• 🚀 Uso Básico
• 💡 Exemplos Práticos
• ❓ FAQ

Guia do Desenvolvedor

• 🏗️ Arquitetura
• 🔧 Exemplos Técnicos
• 🤝 Como Contribuir

Referência

• 📚 API Reference
• 🛠️ Ferramentas
• ⌨️ Comandos

Build Local da Documentação

poetry run mkdocs serve
# Acesse: http://localhost:8000

🔧 Configuração

Variáveis de Ambiente

Crie um arquivo .env:

# OpenAI
OPENAI_API_KEY=sk-proj-xxx...

Configuração do Modelo

config = {
    "temperature": 0.7,     # Criatividade (0-1)
    "max_tokens": 1000,     # Limite de resposta
    "top_p": 0.9,           # Nucleus sampling
    "think": True,          # Ollama: bool / OpenAI: "low"|"medium"|"high"
}

agent = CreateAgent(
    provider="openai",
    model="gpt-4",
    name="Assistente",
    instructions="Seja conciso",
    config=config,
    history_max_size=20
)

📊 API Reference

CreateAgent

CreateAgent(
    provider: str,              # "openai" ou "ollama" (obrigatório)
    model: str,                 # Nome do modelo (obrigatório)
    name: str = None,           # Nome do agente (opcional)
    instructions: str = None,   # Instruções do sistema (opcional)
    config: dict = None,        # Configuração do modelo (opcional)
    tools: list = None,         # Lista de ferramentas (opcional)
    history_max_size: int = 10  # Tamanho máximo do histórico
)

Métodos Principais

📖 Documentação completa da API

🤝 Contribuindo

Contribuições são bem-vindas! Siga os passos:

1. Fork o repositório

2. Crie uma branch: git checkout -b feature/nova-feature

3. Implemente seguindo os padrões existentes

4. Adicione testes: Garanta cobertura mínima de 70%

5. Execute os checks:

   # Instalar pre-commit hooks
   poetry run pre-commit install
   
   # Executar todos os checks
   poetry run pre-commit run --all-files
   
   # Executar testes com cobertura
   poetry run pytest --cov=src --cov-fail-under=70
   

6. Envie um Pull Request

Adicionando um Novo Provedor

1. Crie um novo adapter em src/infra/adapters/NomeProvedor/
2. Implemente a interface ChatRepository
3. Registre em ChatAdapterFactory
4. Adicione testes em tests/infra/adapters/

Exemplo:

class MeuAdapter(ChatRepository):
    async def chat(self, message: str) -> str:
        # Sua implementação
        pass

📖 Guia completo de contribuição

🧪 CI/CD & Workflows

Este projeto tem automação profissional com GitHub Actions:

Quality Checks (CI)

• Executa em: Push/PR para develop ou main
• Matrix: Python 3.12, 3.13, 3.14
• Checks:
  • ✅ Lint (Black, Ruff, isort)
  • ✅ Type checking (mypy)
  • ✅ Security (Bandit, detect-secrets)
  • ✅ Tests com cobertura mínima de 70%
  • ✅ Docstring validation (pydocstyle)

Documentation Build

• Executa: Manualmente via workflow_dispatch
• Ação: Build e validação da documentação com MkDocs

Pre-commit Hooks

15+ verificadores automáticos antes de cada commit:

# Instalar
poetry run pre-commit install

# Executar manualmente
poetry run pre-commit run --all-files

📄 Licença

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

📞 Suporte

• 📖 Documentação Completa
• 🐛 Reportar Bugs
• 💬 Discussões
• 📧 Email: estraliotojordan@gmail.com

👨‍💻 Autor

Jordan Estralioto

• GitHub: @jor0105
• Email: estraliotojordan@gmail.com

📚 Referências

• Clean Architecture - Robert C. Martin
• OpenAI API Documentation
• Ollama Documentation
• SOLID Principles