The Neuro-Symbolic Backbone for Agents & Automation.
Trellis é um Motor de Máquina de Estados Determinístico (Deterministic State Machine Engine) para a construção de CLIs, ChatOps resilientes e Guardrails para Agentes de IA (Neuro-Symbolic).
Atuando como a espinha dorsal lógica do sistema, ele impõe estritamente as regras de negócio e transições permitidas, enquanto sua interface (ou LLM) gerencia apenas a apresentação.
Mais do que um engine, é uma plataforma de Durable Execution que permite a suspensão e retomada de processos longos, habilitando padrões avançados como SAGA (Orquestração de Transações e Compensação).
Hybrid Nature: Use como Framework (CLI + Markdown) para prototipagem rápida, ou como Biblioteca (Go) para controle total em seu backend. "Opinionated by default, flexible under the hood."
O Trellis preenche a lacuna entre a Rigidez dos Processos e a Flexibilidade da Inteligência:
- Para Agentes de IA: Substitua "If/Else" frágeis e Prompts gigantes por um grafo de estados auditável. O Trellis impede alucinações de fluxo.
- Para Humanos: Funciona como um motor de Workflow as Code (similar a um n8n/Zapier, mas compilado e versionável), ideal para CLIs complexas e automação de Ops.
graph TD
%% Nodes
Brain["🧠 Cérebro (LLM) ou<br/>👤 Humano (CLI)"] -->|Intenção / Input| Trellis["🛡️ Espinha Dorsal<br/>(Trellis Engine)"]
subgraph "Mundo Simbólico (Determinístico)"
Trellis -->|Validação| Rules["📜 Regras de Negócio<br/>(State Machine)"]
Rules -->|Ok / Block| Trellis
end
Trellis -->|Execução Segura| Tools["⚡ Ferramentas<br/>(API / DB / Scripts)"]
Tools -->|Resultado| Trellis
Trellis -->|Contexto Atualizado| Brain
%% Styles
style Brain fill:#f9f,stroke:#333,stroke-width:2px,color:black
style Trellis fill:#9cf,stroke:#333,stroke-width:2px,color:black
style Rules fill:#ff9,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:black
style Tools fill:#9f9,stroke:#333,stroke-width:2px,color:black
O decisor (seja IA ou Humano) escolhe qual caminho tomar, mas o Trellis garante que ele existe e é válido.
Coreografamos sua lógica em um Grafo de Estados. Você define Nós (Passos) e Transições (Regras), e o Trellis gerencia a navegação.
Você pode definir esse grafo de duas formas:
Ideal para prototipagem, visualização (Mermaid) e edição por LLMs. Suporta Markdown (Frontmatter), YAML ou JSON via Loam.
# start.yaml
type: question
content: Olá! Qual é o seu nome?
save_to: user_name # Data Binding automático
to: greeting # Transição incondicionalIdeal para integração profunda em backends, performance crítica e type-safety total.
&domain.Node{
ID: "start",
Type: "question",
Content: []byte("Olá! Qual é o seu nome?"),
SaveTo: "user_name",
Transitions: []domain.Transition{{ToNodeID: "greeting"}},
}Nota: Ambas as formas geram a mesma estrutura em memória e podem co-existir (ex: carregar arquivos e injetar nós via código).
- Data Binding & Contexto: Capture inputs (
save_to) e use variáveis ({{ .name }}) nativamente. - Namespaces (Sub-Grafos): Organize fluxos complexos em pastas e módulos (
jump_to), escalando sua arquitetura. - MCP Server: Integração nativa com Model Context Protocol para conectar Agentes de IA (Claude, Cursor, etc.).
- Strict Typing: Garante que seus fluxos sejam robustos e livres de erros de digitação (Zero "undefined" errors).
- Embeddable & Agnostic: Use como CLI, Lib ou Service. O Core é desacoplado de IO e Persistência (Hexagonal).
- Error Handling: Mecanismo nativo de recuperação (
on_error) para ferramentas que falham. - Native SAGA Support: Orquestração de transações distribuídas com
undoerollbackautomático. - Hot Reload: Desenvolva com feedback instantâneo (SSE) ao salvar seus arquivos.
A forma mais fácil de instalar no Windows é via Scoop:
# 1. Adicione o bucket (apenas a primeira vez)
scoop bucket add aretw0 https://github.com/aretw0/scoop-bucket
# 2. Instale o Trellis
scoop install trellisInstale via Homebrew:
brew install aretw0/tap/trellisPara usar o Trellis como biblioteca dentro do seu backend (sem arquivos, puramente em memória):
go get github.com/aretw0/trellis// Exemplo: Instanciando o Engine sem ler arquivos
loader, _ := memory.NewFromNodes(myNodes...)
eng, _ := trellis.New("", trellis.WithLoader(loader))# Execução do Engine (Demo)
go run ./cmd/trellis ./examples/tour# Modo Interativo (Terminal)
go run ./cmd/trellis run ./examples/tour
# Modo HTTP Server (Stateless API)
go run ./cmd/trellis serve --dir ./examples/tour --port 8080
# Swagger UI disponível em: http://localhost:8080/swagger
# Modo MCP Server (Para Agentes de IA)
go run ./cmd/trellis mcp --dir ./examples/tour
# Modo Debug (Observability)
go run ./cmd/trellis run --debug ./examples/observability
# Exemplo Global Signals (Interrupts)
go run ./cmd/trellis run ./examples/interrupt-demo
# Exemplo Tool Safety & Error Handling
go run ./cmd/trellis run ./examples/tools-demo
# Exemplo Log Estruturado (Production Recipe)
go run ./examples/structured-loggingVisualize seu fluxo como um grafo Mermaid:
trellis graph ./my-flow
# Saída: graph TD ...Usando Makefile (Recomendado):
make gen # Gera código Go a partir da spec OpenAPI
make serve # Roda servidor com exemplo 'tour'
make test # Roda testesHot Reload Manual: Itere mais rápido observando mudanças de arquivo:
trellis run --watch --dir ./my-flowO engine monitorará seus arquivos .md, .json, .yaml. Ao salvar, a sessão recarrega automaticamente (preservando o loop de execução).
- 📖 Product Vision & Philosophy
- 🏗 Architecture & Technical Details
- 🌐 Guide: Running HTTP Server (Swagger)
- 🎮 Guide: Interactive Inputs
- 💾 Guide: Session Management (Chaos Control)
- 📅 Roadmap & Planning
- ⚖️ Decisões de Arquitetura
trellis/
├── cmd/ # Entrypoints (trellis CLI)
├── docs/ # Documentação do Projeto
├── examples/ # Demos e Receitas (Tours, Patterns)
├── internal/ # Implementação Privada (Runtime, TUI)
├── pkg/ # Contratos Públicos (Facade, Domain, Ports, Adapters)
└── tests/ # Testes de Integração (Certification Suite)