The Neuro-Symbolic Backbone for Agents & Automation.
Trellis e um motor deterministico de fluxos para orquestrar ferramentas, scripts e guardrails com previsibilidade. Use como framework de CLI/Markdown ou como biblioteca Go dentro do seu backend.
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."
- CLIs e Ops: fluxos guiados, com validacao e auditabilidade.
- Automacao de ferramentas: scripts e APIs encadeados como um grafo versionavel.
- Agentes com governanca: guardrails reais, sem depender apenas de prompt.
- Backends duraveis: execucoes longas com pause/resume e padroes SAGA.
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.
Voce define um Grafo de Estados com Nos (Passos) e Transicoes (Regras), e o Trellis gerencia a navegacao.
Voce 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).
Para produto e UX
- Data Binding & Contexto: Capture inputs (
save_to) e use variaveis ({{ .name }}) nativamente. - Namespaces (Sub-Grafos): Organize fluxos complexos em pastas e modulos (
jump_to). - MCP Server: Integracao nativa com Model Context Protocol para conectar Agentes de IA.
Para engenharia
- Strict Typing: Garante que seus fluxos sejam robustos e livres de erros de digitacao.
- Embeddable & Agnostic: Use como CLI, Lib ou Service. O Core e desacoplado de IO e Persistencia.
- Native SAGA Support: Orquestracao de transacoes distribuidas com
undoerollbackautomatico.
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))# Execucao do Engine (Demo)
trellis run ./examples/tourSe voce estiver desenvolvendo dentro do repo, veja a secao "Modo de Desenvolvimento" abaixo.
# Modo Interativo (Terminal)
trellis run ./examples/tour
# Modo HTTP Server (Stateless API)
trellis serve --dir ./examples/tour --port 8080
# Swagger UI disponível em: http://localhost:8080/swagger
# Modo MCP Server (Para Agentes de IA)
trellis mcp --dir ./examples/tourDetalhes e variacoes em:
Visualize 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 testesExecutar direto do repo (Go):
go run ./cmd/trellis run ./examples/tour
go run ./cmd/trellis serve --dir ./examples/tour --port 8080
go run ./cmd/trellis mcp --dir ./examples/tourHot 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)
- 🧭 Node Syntax Reference
Mais em docs/.
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)