Documentation Index
Fetch the complete documentation index at: https://docs.aiparlance.org/llms.txt
Use this file to discover all available pages before exploring further.
Especificação
Documento normativo do AI Parlance (v0.1). Define gramática, semântica, builtins, políticas e níveis de estabilidade dos blocos.
Visão geral: Introdução. Sintaxe: Sintaxe.
Glossário
| Termo | Significado |
|---|
| AI Parlance | Linguagem declarativa AI-first usada como IR entre intenção e código gerado. |
| Bloco | Construção de topo (entity, workflow, …). |
| Transpilador | Gerador que converte AI Parlance (+ AST) em artefatos de um alvo (Go, SQL, …). |
| AST | Árvore sintática produzida pelo parser a partir do texto .aip. |
| Builtin | Função ou comando reservado (now(), notify(), …). |
| Predicado | Expressão booleana em policy (authenticated, role(admin), …). |
Escopo e limites
AI Parlance cobre hoje:
- modelagem de dados e API (CRUD)
- autorização declarativa
- workflows e eventos de domínio limitados
Não substitui:
- UI custom ou design system
- algoritmos complexos ou otimizações manuais
- integrações ad hoc sem bloco dedicado
- SQL imperativo escrito à mão (bloco
custom reservado para o futuro; fora do v0.1)
| Ferramenta | Foco | AI Parlance |
|---|
| OpenAPI / AsyncAPI | Contratos HTTP / eventos | Modelo + comportamento + policy numa spec |
| Prisma / DBML | Schema de dados | Entidades + relações + migrations multi-target |
| OPA / Cedar | Autorização | policy integrada ao modelo de entidades |
| Temporal / Cadence | Orquestração imperativa | workflow declarativo para regras comuns |
Pipeline
Prompt ou edição humana
↓
Texto .aip
↓
Parser → AST
↓
Validador semântico
↓
Transpiladores (por alvo)
↓
Go, SQL, OpenAPI, workers, …
.aip é a fonte; a AST é representação interna.
Toolchain (v0.1): parser, validador e transpiladores ainda não publicados. Este documento é a fonte normativa; gramática em spec/v0.1/grammar.ebnf.
Bloco app obrigatório
Toda spec v0.1 deve começar com exatamente um bloco app (recomendado @0.1):
app MinhaApp @0.1 {
database postgres
}
auth ao usar authenticated, role ou permission em policy. Exemplo mínimo: examples/minimal.aip.
Gramática (EBNF resumida)
program = { block } ;
block = app_block | entity_block | crud_stmt | policy_block
| index_block | api_block | workflow_block | event_block
| lifecycle_block | seed_block | job_block | queue_block
| ai_context_block ;
app_block = "app" IDENT [ "@version" ] "{" app_member { app_member } "}" ;
entity_block = "entity" IDENT "{" { field_decl | entity_modifier } "}" ;
field_decl = IDENT ":" type_expr [ field_modifier { field_modifier } ] ;
crud_stmt = "crud" IDENT ;
workflow_block = "workflow" IDENT "{" when_clause { stmt } "}" ;
when_clause = "when" IDENT "." lifecycle_event ;
required | optional → unique → default(...).
Comentários de linha: // até o fim da linha.
Níveis de estabilidade
| Nível | Blocos | Status v0.1 |
|---|
| Core | app, entity, crud, validação inline; tipos enum(…) inline; relações belongs_to inline | Estável |
| Infra | index, api, migrations, seed, naming; modificadores timestamps, soft_delete em entity | Estável |
| Security | auth (em app), policy, predicados | Beta |
| Behavior | workflow, event, lifecycle, job, queue; statements em workflow (emit, create, …) | Beta |
enum { } / relation { } e has_one / has_many / many_to_many estão no roadmap, não no v0.1.
Blocos beta podem mudar entre releases v0.x menores. O Core é estável dentro do v0.1; a spec global permanece rascunho até existir toolchain de referência.
Campos implícitos
Toda entity recebe automaticamente (salvo id: uuid explícito):
| Campo | Tipo | Notas |
|---|
id | uuid | Primary key |
created_at | datetime | Sempre injetado (padrão Core) |
updated_at | datetime | Sempre injetado (padrão Core) |
timestamps em entity é documentação opcional; não desativa esses campos.
soft_delete em entity adiciona deleted_at: datetime optional.
Builtins
| Nome | Uso | Efeito |
|---|
now() | expressões | Data/hora UTC atual |
available_seller() | workflow | Retorna User seller disponível |
assign | assign Lead.seller seller | Atribui FK / relação |
notify(recipient, message) | workflow | Notificação; recipient é variável User, campo ou literal |
LeadExists(phone) | condição | Duplicidade por telefone normalizado |
normalize_phone(value) | expressão | Normaliza telefone |
emit EventName { … } | workflow | Publica evento de domínio |
create Entity { … } | workflow | Cria registro da entidade |
reject "msg" | workflow | Erro de negócio |
dispatch JobName | workflow | Enfileira job |
Ciclo de vida
Eventos de sistema (gatilhos de when):
created | updated | deleted
lifecycle Lead {
on created -> workflow LeadReceived
before create {
normalize_phone(Lead.phone)
}
after update {
notify(Lead.seller, "Lead atualizado")
}
}
when Lead.created em workflow equivale a on created em lifecycle. Prefira lifecycle com vários ganchos na mesma entidade.
Statements de workflow (v0.1)
Dentro de workflow / ganchos de lifecycle: var, if / reject, assign, create, emit, notify, dispatch (opcional after + duração). Durações: 15m, 1h, 1d — ver Workflows.
Referências forward são válidas: emit e create podem usar event / entity declarados depois no arquivo.
Políticas
| Predicado | Significado |
|---|
public | Sem autenticação |
authenticated | JWT/sessão válida |
role(name) | Papel global |
permission(name) | Permissão concedida |
owner(field) | Usuário autenticado igual a field |
owner_or_manager(field) | owner ou role(manager) ou role(admin) |
policy Lead {
read owner_or_manager(Lead.seller)
}
Lead.seller como belongs_to User.
Acesso padrão
Entidades sem policy: transpiladores devem usar authenticated no CRUD quando app tem auth, ou public sem auth. policy explícita prevalece.
Propostos (fora da gramática v0.1)
- Declaração top-level
permission nome
- Blocos
endpoint para rate limit por rota
Preview em Segurança até entrarem na gramática.
Validação
O validador deve rejeitar:
- ausência ou duplicata do bloco
app
- referência a
entity / event / job inexistente
policy sem auth no app quando usar authenticated ou roleowner(field) com campo inexistenteworkflow sem when- modificadores duplicados ou fora de ordem (warning vs error por regra)
- builtins não registrados
Matriz de transpiladores
| Alvo | Artefatos | Status v0.1 |
|---|
| PostgreSQL | DDL, migrations, índices | Planejado (alvo principal da linguagem) |
| MySQL | DDL, migrations | Planejado (database mysql no app; sem transpiler ainda) |
| Go | structs, handlers, middleware JWT | Planejado |
| TypeScript | interfaces, guards | Planejado |
| Python | models, decorators | Planejado |
| PHP | classes, policies | Planejado |
| OpenAPI | paths, schemas, security | Planejado |
| Docs | Markdown / referência API | Planejado |
| Testes | fixtures CRUD | Planejado |
| Workers | filas, jobs | Planejado |
.aip, não na transpilação offline.
Spec de referência
Exemplo CRM: examples/crm-reference.aip
Capítulos de domínio documentam extensões em relação a esse arquivo.