createagents 0.2.0

A powerful and accessible framework for creating AI agents and automation workflows

🤖 Create Agents AI

Framework Python enterprise para criar agentes de IA inteligentes com arquitetura limpa, múltiplos provedores e ferramentas extensíveis.

Documentação • Exemplos • API Reference • Contribuir

---

🎯 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

Provedor	Status
OpenAI	✅ Estável
Ollama	✅ Estável

🔧 Ferramentas Built-in

Ferramenta	Descrição	Instalação
CurrentDateTool	Data/hora em qualquer timezone	Padrão
ReadLocalFileTool	Lê PDF, Excel, CSV, Parquet, JSON, YAML, TXT	poetry install -E file-tools

📊 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

import asyncio
from createagents import CreateAgent

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

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

asyncio.run(main())

Com Ferramentas

import asyncio
from createagents import CreateAgent

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

    # O agente usa ferramentas automaticamente
    response = await agent.chat("Que dia é hoje?")  # Usa CurrentDateTool
    print(response)

asyncio.run(main())

Ollama (Local)

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

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

Agente Local com Ollama

import asyncio
from createagents import CreateAgent

async def main():
    agent = CreateAgent(
        provider="ollama",
        model="llama3.2",
        instructions="Você é um assistente local"
    )

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

asyncio.run(main())

---

📋 Exemplos de Uso

Exemplo 1: Assistente de Programação

import asyncio
from createagents import CreateAgent

async def main():
    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
    resposta = await assistant.chat("Como ordenar uma lista de dicionários por chave?")
    print(resposta)

    # 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()

asyncio.run(main())

Exemplo 2: Múltiplos Agentes

import asyncio
from createagents import CreateAgent

async def main():
    # 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"

    analise = await analyzer.chat(f"Analise este código: {code}")
    print("Análise:", analise)

    docs = await documentor.chat(f"Documente esta função: {code}")
    print("\nDocumentação:", docs)

asyncio.run(main())

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

Método	Retorno	Descrição
chat(message)	str	Enviar mensagem e receber resposta
get_configs()	dict	Obter configurações e histórico
clear_history()	None	Limpar histórico de mensagens
get_all_available_tools()	dict	Listar todas as ferramentas (sistema + customizadas)
get_system_available_tools()	dict	Listar apenas ferramentas do sistema
get_metrics()	list	Obter métricas de performance
export_metrics_json(path=None)	str	Exportar métricas em JSON
export_metrics_prometheus(path=None)	str	Exportar métricas em Prometheus

📖 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: [e-mail]

---

👨‍💻 Autor

Jordan Estralioto

• GitHub: @jor0105
• Email: [e-mail]

---

📚 Referências

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

---

Versão: 0.2.0 Última atualização: 02/12/2025 Status: 🚀 Projeto publicado! Aberto para contribuições e sugestões.

⭐ Se este projeto foi útil, considere dar uma estrela no GitHub!