Archetype

Type-safe markdown at every agent boundary.

Archetype gives you the tools — backed by Pydantic models — to validate data at agent boundaries and guide agent behavior. In agentic systems, structured data moves between agents as LLM-generated markdown — patient assessments, contract analyses, audit findings, software designs. Because this data is generated and non-deterministic, producers and consumers diverge silently: a required section gets dropped, a heading gets renamed, a field comes back in the wrong format. Nothing catches it, so the error propagates through the system.

Archetype makes the Pydantic model the contract at every agent boundary. At boundaries, it injects the markdown contract into agent instructions and validates markdown the agent generates. Inside agents, field descriptions from the model provide semantic context in prompts. One change to the Pydantic model propagates to every touchpoint of the corresponding markdown file.

Capabilities

Installation

pip install archetype-md

Quickstart

Given this model:

from typing import Annotated

from archetype.markdown import (
    AsBulletList,
    AsHeading,
    MarkdownDocument,
    MarkdownHeader,
    TextTemplate,
    generate_contract,
    parse_markdown_as,
    render_markdown,
)

class Finding(MarkdownHeader):
    heading: Annotated[str, TextTemplate("Finding {ordinal} — {value}")]
    recommendations: Annotated[list[str], AsBulletList()]
    description: Annotated[str, AsHeading()]

class Review(MarkdownDocument):
    heading: Annotated[str, TextTemplate("{value}")]
    summary: Annotated[str, AsHeading()]
    findings: list[Finding]

# Generate the markdown contract to embed in an agent instruction
contract = generate_contract(Review)

# Parse markdown back into a validated model instance
review = parse_markdown_as(produced_markdown, Review)

# Render a populated instance back to markdown
output = render_markdown(review)

A populated document — what render_markdown produces and parse_markdown_as consumes — looks like this:

# Q4 Code Review

## Summary

Two issues found, both fixable with minor changes.

## Findings

### Finding 1 — SQL Injection in login handler

- Use parameterised queries
- Validate all user input at the controller layer

#### Description

The login handler at auth.py:42 builds SQL by string concatenation,
allowing an attacker to inject arbitrary SQL.

### Finding 2 — Missing rate limit on password reset

- Add a rate limit of 5 requests per minute per IP
- Return a generic error message to avoid user enumeration

#### Description

The password reset endpoint accepts unlimited requests,
enabling brute-force and enumeration attacks.

Modules

archetype.markdown

Typed markdown documents backed by Pydantic models.

Field annotations (attached via Annotated[T, ...]):

archetype.templating

Jinja-based template resolution with markdown-aware globals.

from archetype.templating import resolve

instructions = resolve(
    template_text,
    feature=state.feature_definition,
)

resolve runs with strict undefined semantics — any missing variable raises jinja2.UndefinedError immediately. Two globals are available inside every template: template_fields(ModelClass) and generate_contract(ModelClass).

Design

The model is the contract. Annotations on fields drive all rendering and parsing behaviour. No separate config, no code generation — change the model, everything updates.

Strict by default. parse_markdown_as raises MarkdownValidationError with field-localized messages on any mismatch. resolve raises on undefined template paths. Silent partial results are not produced.

Development

pdm install
pdm run test
pdm run lint
pdm run check-format
pdm run typecheck