epi-lang 0.3.3

Epi — Epistemic Programming Interface

A type discipline for AI-augmented full-stack applications

Research status: v0.3 — active development, structural validation phase.

Authors: Randerson Rebouças (PhD candidate, UFRGS), Dante Barone, and Eliseo Reátegui, PPGIE/UFRGS. The short paper "Epi: An Epistemic Type System for Containing LLM Hallucination in Generated Code" was accepted at SBLP 2026, the 30th Brazilian Symposium on Programming Languages, part of CBSoft 2026.

Accepted paper: paper/Epi-SBLP2026-camera-ready.pdf (camera-ready). This repository is the artifact for that paper; the archived snapshot is at doi.org/10.5281/zenodo.21433256.

What Epi is

Epi is a domain-specific language whose type system makes the epistemic boundary between deterministic computation and AI inference explicit. From a single .epi source, the transpiler generates a complete Next.js project — database schema, API routes, auth middleware, runtime validators, LLM inference calls, and UI components — such that AI-inferred values cannot bypass validation.

The thesis is narrow and honest: LLM hallucination cannot be prevented, but it can be contained at a type-system boundary, by construction, in the generated code.

What problem this solves

In a typical AI-augmented app, validation of LLM outputs, confidence thresholding, fallback handling, and audit trails are all optional — features the developer must remember to add. They get omitted in practice.

Epi makes them structural consequences of the type. A declaration like

risco: AI.Enum(Alto, Medio, Baixo, strict: true, confidence_threshold: 0.85)

necessarily produces:

1. A database column (deterministic, Prisma).
2. A Zod schema constraining the LLM output at runtime.
3. An LLM inference call with confidence reporting.
4. A checkpoint route that pauses for human review when confidence is below threshold.

You cannot compile an Epi program with an AI field and forget to validate the output. The transpiler emits the contract.

Example

@Language: Epi v0.3
@Goal: "Contract Analysis with Human-in-the-loop"

Entity Contrato {
    id: UUID(auto),
    titulo: Text,
    documento: Text,
    valor: Decimal,
    criado_em: DateTime(auto),
    risco: AI.Enum(Alto, Medio, Baixo, strict: true)
}
//       ▲ Rigid: deterministic    ▲ Epistemic: AI-inferred, validated at the boundary

Guard SomenteAdvogados {
    Condition: Auth.Role == "Lawyer"
}

Pulse ExtrairRisco {
    Input: Contrato
    Protect: Guard.SomenteAdvogados
    Process:
        Execute: AI.scan(
            source: Input.documento,
            prompt: file("@prompts/legal_scan.md"),
            temperature: 0.1,
            on_fail: Fallback.ManualReview(Queue: "Advogados")
        )
    Output: Contrato.risco
}

Pipeline AnalisarContrato {
    Flow: ExtrairRisco -> GerarResumo -> Notificar
    On_Error: Retry(max: 3, backoff: exponential)
}

Lens Dashboard {
    Mood: "Clean, Legal-Tech"            // [experimental]
    Display:
        Table(Contrato, columns: [titulo, valor, risco]),
        Form(Contrato) -> Button("Analisar").trigger(ExtrairRisco)
}

Fewer than 80 lines. The transpiler generates the entire Next.js project — schema, middleware, routes, validators, LLM calls, UI — with the epistemic contract enforced.

When to use Epi

• Domains where audit-by-construction is required: legal, healthcare, education, government.
• Apps where AI-inferred values must be persisted and traceable, not just shown.
• Focused LLM-augmented products, not general-purpose AI platforms.
• Settings where human-in-the-loop is structural (Trace + Checkpoint maps naturally).
• Domains with a meaningful prior distribution (Bayesian update genuinely helps).

When NOT to use Epi

• Conversational chatbots or customer-support assistants.
• Apps centered on complex RAG, multi-tool agents, or fine-tuning workflows.
• Teams with a mature in-house AI platform (LangGraph custom, internal orchestration).
• Pure creative generation (confidence and checkpoint don't apply).
• Latency-critical paths under 100 ms; Epi is for decision-grade flows.

See docs/LIMITATIONS.md for the full honest list of gaps in v0.3.

Architecture

A three-layer transpiler. The LLM is formally excluded from Layers 1 and 2.

.epi source
   ▼
[Layer 1: Parser]            Lark + EBNF              100% deterministic
   ▼
[Layer 2: Rigid Generator]   Prisma, middleware,      100% deterministic
                             routes, Zod validators
   ▼
[Layer 3: Epistemic Gen.]    LLM calls, Trace,        validated by Layer 2
                             Checkpoint, Lens

See docs/ARCHITECTURE.md for the full breakdown.

Requirements

To run the transpiler:

To build and run a project the transpiler generates:

To reproduce the containment evaluation of the paper (eval/):

Developed and measured on macOS 15 (Apple Silicon, 16 GB RAM). Nothing in the toolchain is platform-specific, but no other platform has been exercised.

Installation

pip install epi-lang

Or from source, which is also what you need for the example programs and the evaluation harness:

git clone https://github.com/RandMelville/epi-lang.git
cd epi-lang
pip install -e ".[dev]"

Check that it works

The fastest end-to-end check needs no database, no API key and no Node:

epi validate examples/avaliacao-simples.epi
epi transpile examples/avaliacao-simples.epi --outdir ./generated
ls generated

That parses the program of Section 5 of the paper and writes the generated project (13 files, 477 lines) to ./generated. The full test suite:

pytest

Run a generated project

cd generated
npm install
cp .env.example .env
# Set DATABASE_URL, then pick a provider:
#   EPI_AI_PROVIDER=anthropic + ANTHROPIC_API_KEY=sk-ant-...
#   EPI_AI_PROVIDER=ollama    (requires `ollama serve`)
npx prisma migrate dev --name init
npm run dev

Reproduce the paper's evaluation

cd eval
./setup.sh

See eval/README.md for the harness, the 40-item dataset with gold labels, and the raw per-call results behind Table 2.

The five primitives

The epistemic type system

Two domains.

Rigid types — deterministic, no AI involvement:

UUID(auto)   Text   Int   Float   Decimal   Bool   DateTime(auto)   JSON

Epistemic types — AI-inferred, runtime-validated:

AI.Enum(values..., strict, prior, confidence_threshold)
AI.Text(max_tokens)
AI.Classification(labels)
AI.Score(min, max)
AI.Embedding(dimensions)

A single epistemic declaration generates a database column, a Zod validator, an LLM inference call, and optionally a checkpoint route. If it compiles, the runtime contract is enforced.

Trace + Checkpoint (v0.3 highlight)

A Pulse can be decomposed into Trace steps. Each step can Expose: intermediate reasoning fields and pause at a Checkpoint: for human review before the final output is committed.

Pulse AvaliarRespostaAluno {
    Trace CompreenderEnunciado {
        Execute: AI.reason(source: Input.enunciado, prompt: file("@prompts/..."))
        Expose: interpretacao, conceitos_chave, criterios_avaliacao
        Checkpoint: ReviewRequired(role: "Professor")
    }

    Trace AvaliarResposta {
        Execute: AI.classify(
            source: Input.resposta_aluno,
            confidence_threshold: 0.85,
            on_low_confidence: Checkpoint.ReviewRequired(role: "Professor")
        )
    }
}

This generates an in-memory TraceState store, inspect / resume HTTP routes, and an audit trail of every human approval or correction. Designed for high-stakes evaluation flows (pedagogical assessment, legal review, clinical triage).

Documentation

Status

Stable in v0.3:

• EBNF grammar (Lark)
• AST with epistemic type system (Pydantic)
• Parser + Lark transformer
• Deterministic generators: Prisma schema, middleware, routes, Zod validators
• Epistemic generators: LLM calls, Trace + Checkpoint, Bayesian prior
• Provider-agnostic LLM client in the generated project: Anthropic, or any OpenAI-compatible endpoint, with Ollama used for local open-weight models. Selected by EPI_AI_PROVIDER at deployment, with no change to the .epi source.
• CLI: validate, parse, transpile
• 127 tests passing (pytest)
• PyPI package (pip install epi-lang)

Experimental — known to be incomplete:

• Lens.Mood — deterministic keyword-to-Tailwind lookup of 6 hardcoded moods. Not LLM-generated UI; do not rely on it.
• --target fastapi — blocked in the CLI; current output is inconsistent.

Planned for v0.4:

• Gemini and a broader provider matrix on top of the existing adapter.
• epi init for project bootstrap without cloning the repo.
• FastAPI target completion (or formal removal).
• Empirical evaluation study (Epi-generated vs hand-written equivalents).
• SQLite option for quickstart without local Postgres.

Related work

Citation

@software{reboucas2026epi,
  author  = {Rebouças, Randerson Oliveira Melville and Barone, Dante Augusto Couto and Reátegui, Eliseo},
  title   = {Epi: An Epistemic Type System for Containing LLM Hallucination in Generated Code},
  year    = {2026},
  url     = {https://github.com/RandMelville/epi-lang},
  version = {0.3.2},
  doi     = {10.5281/zenodo.21433256}
}

The paper was accepted at SBLP 2026 (30th Brazilian Symposium on Programming Languages, CBSoft 2026).

Contributing

See docs/CONTRIBUTING.md. Honest critique preferred over wishful documentation.

License

Apache License 2.0 — Copyright (c) 2026 Randerson Rebouças.