Metadata-Version: 2.4
Name: epi-lang
Version: 0.3.1
Summary: Epi — Epistemic Programming Interface. A zero-stack intent-oriented language with an epistemic type system that formally separates deterministic and AI-inferred computation.
Project-URL: Homepage, https://github.com/RandMelville/epi-lang
Project-URL: Source, https://github.com/RandMelville/epi-lang
Project-URL: Issues, https://github.com/RandMelville/epi-lang/issues
Project-URL: Documentation, https://github.com/RandMelville/epi-lang/tree/main/docs
Project-URL: Paper, https://github.com/RandMelville/epi-lang/blob/main/docs/PAPER.md
Project-URL: Specification, https://github.com/RandMelville/epi-lang/blob/main/docs/SPEC.md
Author-email: Randerson Rebouças <randerson.melville@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,code-generation,dsl,epistemic,intent-oriented,language,transpiler,type-system,zero-stack
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1.0
Requires-Dist: lark>=1.1.9
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: anthropic>=0.40.0; extra == 'all'
Requires-Dist: mypy>=1.10.0; extra == 'all'
Requires-Dist: pytest-snapshot>=0.9.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-snapshot>=0.9.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: anthropic>=0.40.0; extra == 'fastapi'
Description-Content-Type: text/markdown

<p align="center">
  <strong>Epi</strong> — Epistemic Programming Interface
</p>

<p align="center">
  <em>A type discipline for AI-augmented full-stack applications</em>
</p>

<p align="center">
  <a href="https://github.com/RandMelville/epi-lang/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://pypi.org/project/epi-lang/"><img src="https://img.shields.io/pypi/v/epi-lang?color=orange" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-%3E%3D3.11-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/status-research%20%2F%20active-green.svg" alt="Status">
</p>

---

> **Research status:** v0.3 — active development, structural validation phase.
>
> Author: [Randerson Rebouças](https://github.com/RandMelville) — PhD candidate, UFRGS.
> A short paper is being prepared for SBLP 2026.

## 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

```epi
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

```epi
@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](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](docs/ARCHITECTURE.md) for the full breakdown.

## Quick start

The PyPI package installs the CLI; example `.epi` files currently live in this repo. A `pip-only` workflow lands in v0.4 with `epi init`.

```bash
git clone https://github.com/RandMelville/epi-lang.git
cd epi-lang
pip install epi-lang

# Validate
epi validate examples/contrato.epi

# Transpile to a Next.js project
epi transpile examples/contrato.epi --target nextjs --outdir ./generated

cd generated
npm install
cp .env.example .env
# Edit .env: DATABASE_URL=postgresql://...  and  ANTHROPIC_API_KEY=sk-ant-...
npx prisma migrate dev --name init
npm run dev
```

For development:

```bash
pip install -e ".[dev]"
pytest
```

## The five primitives

| Primitive | What it does | Status |
|---|---|---|
| **Entity** | Data schema with typed fields, rigid + epistemic | stable |
| **Guard** | Auth & authorization, transpiles to middleware | stable |
| **Pulse** | AI execution unit with `temperature`, `prompt`, `on_fail` | stable |
| **Pipeline** | Composes Pulses with retry/backoff strategy | stable |
| **Lens** | Semantic UI declaration | `Display` / `Inject` stable; `Mood` experimental |

## 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.

```epi
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

| Document | Purpose |
|---|---|
| [docs/SPEC.md](docs/SPEC.md) | Formal language specification (English, canonical) |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Transpiler architecture and design decisions |
| [docs/MANIFESTO.md](docs/MANIFESTO.md) | Why epistemic types matter |
| [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | What Epi does NOT do (honest list of gaps) |
| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | How to contribute |
| [docs/PAPER.md](docs/PAPER.md) | Paper draft (SBLP 2026 in preparation) |
| [docs/translations/SPEC-PT.md](docs/translations/SPEC-PT.md) | Portuguese translation (may lag) |

## 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 (Anthropic), Trace + Checkpoint, Bayesian prior
- CLI: `validate`, `parse`, `transpile`
- 121 tests passing
- 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:**
- Multi-provider LLM adapter (Ollama, OpenAI, Gemini, Anthropic) — currently Anthropic-only.
- `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

| System | Relationship to Epi |
|---|---|
| [ProbZelus](https://dl.acm.org/doi/10.1145/3385412.3386009) (PLDI 2020) | Separates deterministic and probabilistic reactive streams. Epi lifts the separation to application-level types. |
| [SlicStan](https://dl.acm.org/doi/10.1145/3290348) (POPL 2019) | Information-flow types for probabilistic programs. Epi adapts the discipline to AI-augmented full-stack apps. |
| Russo & Sabelfeld, *Dynamic vs. Static Flow-Sensitive Security Analysis* (CSF 2010) | Information-flow control as type-level separation of security levels — structural analog to Epi's rigid/epistemic separation. |
| [BAML](https://github.com/BoundaryML/baml) | Typed LLM function signatures. Epi extends the idea to whole-application generation. |
| [Wasp](https://wasp-lang.dev) | Full-stack DSL (React + Node). Epi adds epistemic types and AI-aware code generation. |
| [DSPy](https://dspy.ai/) (Stanford) | Declarative LLM programming via signatures. Orthogonal to Epi — DSPy optimizes prompts, Epi separates type domains. |

## Citation

```bibtex
@software{reboucas2026epi,
  author  = {Rebouças, Randerson},
  title   = {Epi: An Epistemic Programming Interface for AI-Augmented Full-Stack Transpilation},
  year    = {2026},
  url     = {https://github.com/RandMelville/epi-lang},
  version = {0.3.0}
}
```

## Contributing

See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). Honest critique preferred over wishful documentation.

## License

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