pyram-flow 0.1.0

Motor de workflows e LLM calling — DAGs, tools, agentes

⚡ Pyram

Workflows & Agentes com IA — DAGs · Tools · LLMs

---

Pyram unifica LLM calling, tool calling e workflows DAG em uma API minimalista.
Zero dependências além de httpx. Sem Pydantic. Sem frameworks. Sem classes abstratas.

---

🚀 Quickstart

# 1. LLM em 3 linhas
from Pyram.llm import DeepSeek
ia = DeepSeek(api_key="sk-...")
print(ia.completetion("Qual a capital do Brasil?").text())

# 2. Tool calling em 5 linhas
from Pyram.tools import tool, sch, exec
@tool(info="Soma dois números")
def add(a: int, b: int) -> int:
    return a + b
resp = ia.completetion("2 + 3?", tools=sch())
print(exec(resp))

# 3. Workflow em 10 linhas
from Pyram.graph import flow, state
@flow
def chatbot():
    if state.pergunta == "preço":
        state.resposta = "R$ 199,90"
    else:
        state.resposta = "Pergunte sobre preços"
resultado = chatbot.run(state={"pergunta": "preço"})
print(resultado.resposta)

---

🧭 Guia rápido

Módulo	O que faz	Documentação
Pyram.llm	6 provedores LLM com interface unificada, tool calling e thinking	📗 docs/llm.md
Pyram.tools	Decorator @tool com schema automático, cache e execução	📗 docs/tools.md
Pyram.graph	Motor de workflows: @flow, @task, DAG, AST, state	📗 docs/graph.md
Pyram.configs	Cache unificado, diretório .PyramCache, TTL	📗 docs/index.md

---

🧠 Provedores LLM

Provider	Classe	Tool Calling	Thinking	Cache
DeepSeek	DeepSeek	✅ Nativo	✅	✅
OpenAI	OpenAI	✅ Nativo	✅	✅
Anthropic	Anthropic	✅ Convertido	✅	✅
Gemini	Gemini	✅ functionDeclarations	❌	✅
Cohere	Cohere	✅ Convertido	✅	✅
Groq	Groq (extends OpenAI)	✅ Nativo	❌	✅

# Interface 100% idêntica entre provedores
resposta = provedor.completetion(
    prompt="...",
    system="Você é um assistente...",
    tools=sch(),           # schemas de ferramentas
    tool_choice="auto",    # "auto" | "any" | "none" | {"function": {"name": "..."}}
    messages=[...],        # histórico completo (opcional)
)
# → CompletionResponse (.text(), .jsn(), .content, .tool_calls, .thinking)

---

🔧 Ferramentas

from Pyram.tools import tool, sch, sch_ant, sch_gem, exec, listar

@tool(info="Busca produtos no estoque")
def buscar_produtos(categoria: str, limite: int = 10) -> list[dict]:
    return [{"nome": "Notebook", "preco": 4500}]

sch()        # → OpenAI format  (DeepSeek, Groq)
sch_ant()    # → Anthropic format
sch_gem()    # → Gemini format
exec(resp, use_cache=True)   # executa com cache

listar()     # → ["buscar_produtos"]

---

🔄 Workflows

from Pyram.graph import flow, task, state, parallel

@task(retry=3, timeout=10, checkpoint=True)
def pagamento():
    state.status = "pago"

@flow
def ecommerce():
    pagamento()
    envio()
    if state.status == "pago":
        notificar()

resultado = ecommerce.run(state={"status": ""})
print(ecommerce.viz())
# pagamento
# ├── envio
# │   └── ? state.status == 'pago'
# │       ├── notificar
# │       │   └── merge
# │       └── [notificar...]

---

📁 Cache Unificado

.PyramCache/
├── responses/
│   ├── deepseek/     # Cache de respostas DeepSeek
│   └── openai/       # Cache de respostas OpenAI
├── tools/            # Cache de execução de tools
└── graph/
    └── {flow_name}/
        ├── checkpoints/  # Checkpoint de tasks
        ├── cache/        # Cache de tasks
        └── manifest.json

from Pyram.configs import Cache

cache = Cache("deepseek", ttl=3600)
cache.set({"model": "deepseek-v4"}, {"choices": [...]})
hit = cache.get({"model": "deepseek-v4"})  # → dict or None

Configure o diretório via export PYRAM_CACHE_DIR=/caminho/do/cache

---

📚 Documentação

Documento	Conteúdo
docs/llm.md	API completa dos 6 provedores, exemplos, detalhes técnicos
docs/tools.md	Decorator @tool, schemas, execução, cache, utilitários
docs/graph.md	@flow, @task, state, condicionais, loops, checkpoint
docs/examples.md	4 exemplos completos: Claude Code Agent, Auto-Correção, E-commerce, Perplexity

---

📄 Licença

MIT — use, modifique, distribua livremente.

---

_{Feito com ☕ e Python puro · GitHub}