typedown 0.2.6

Progressive Formalization for Markdown using Pydantic and Pytest

Typedown: Markdown that scales

Typedown is a Consensus Modeling Language (CML) designed for Literate Modeling. It bridges the gap between the fluidity of human thought (Markdown) and the rigor of engineering (Pydantic + Pytest).

"You don't know it until you model it."

---

The Trinity

Typedown treats Markdown as a first-class language for Consensus as Code (CaC), built on three pillars:

1. Markdown (Interface): Retains natural language expressiveness. It's the habitat for humans and AI.
2. Pydantic (Structure): Defines strict data schemas via model blocks.
3. Pytest (Logic): Enforces business rules and constraints via spec blocks.

Why Typedown?

Traditional tools force a binary choice:

• Liquids (Text/Markdown): High fluidity but zero structural integrity. Documentation rots instantly.
• Crystals (Code/JSON/SQL): High integrity but zero flexibility. Hard for humans to browse and for AI to grasp intent.

Typedown is Active Soft Matter. It allows information to "phase transition" from loose notes into solid, validated models within the same document.

Core Features

• Markdown that scales: Manage thousands of interconnected entities with IDE-grade navigation and validation.
• Progressive Formalization: Start with a sketch, end with a verified system.
• Triple Resolution: Resolve references [[ref]] through Hash (L0), Handle (L1), and Logical ID (L2).
• Evolution Semantics: Track time using former (versioning) to manage history.
• Context-Aware Scoping: Implicit hierarchy via config.td and directory inheritance.
• QC Pipeline: Four-layered validation from syntax (Lint) to external facts (Test).

Quick Start

1. Define a Model

Define your schema directly in Markdown using Python:

```model:UserAccount
class UserAccount(BaseModel):
    name: str
    age: int = Field(..., ge=18)
    role: str = "member"
```

2. Declare an Entity

Instantiate data using YAML with smart reference unboxing:

```entity UserAccount: alice
id: "iam/user/alice-v1"
name: "Alice"
age: 30
role: "admin"
```

3. Write a Specification

Add business logic that targets your data:

```spec id=check_roles
@target(type="UserAccount")
def validate_admin(subject: UserAccount):
    if subject.role == "admin":
        assert subject.age >= 25, "Admins must be senior"
```

CLI Usage

The td tool is your companion for the development loop:

• td lint: (L1) Check Markdown syntax and YAML formatting.
• td check: (L2) Validate entities against Pydantic models.
• td validate: (L3) Check references and run spec blocks (Internal Logic).
• td test: (L4) Run external verification (Oracles/APIs).
• td run <script>: Execute scripts defined in Front Matter.

Installation

Typedown is designed for the uv ecosystem. We recommend using uv or uvx over standard piping.

🚀 Instant Run (Recommended)

Use uvx to execute Typedown instantly without managing environments:

uvx typedown --help

🛠️ Global Tool

Install it as a standalone tool available everywhere:

uv tool install typedown

📦 Project Dependency

Add it to your Python project:

uv add typedown

⌨️ VS Code Extension

Install Typedown Integration from:

• VS Code Marketplace
• Open VSX

Documentation

• GEMINI.md: AI Agent Guidance (Start here for AI dev).
• English Documentation: Explore more about Typedown.
• Chinese Documentation: 核心中文文档.
• Manifesto: Why we built this.

---

License

MIT © IndenScale