lexigram-contracts

Core types and protocols for the Lexigram Framework.

Overview

lexigram-contracts defines all Protocols, base types, Result types, domain models, and exception hierarchies used across the Lexigram ecosystem. It has zero runtime dependencies so it can be imported into any package — including thin integrations — without pulling in the full framework.

This package is the single source of truth for every interface in Lexigram. All other packages depend on contracts; no implementation package defines its own protocol that another package depends on.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-contracts

Quick Start

Result type

from lexigram.result import Result, Ok, Err


async def find_user(user_id: str) -> Result[User, UserNotFound]:
    user = await db.get(user_id)
    if not user:
        return Err(UserNotFound(user_id))
    return Ok(user)


# Safe consumption
result = await find_user("u-123")
name = result.match(ok=lambda u: u.name, err=lambda e: "unknown")

Domain models

from lexigram.domain.models import Entity, ValueObject
from lexigram.domain import AggregateRoot
from lexigram.contracts.domain.events import DomainEvent


class UserCreated(DomainEvent):
    user_id: str
    email: str


class User(AggregateRoot):
    email: str

Protocols

from lexigram.contracts.infra.cache import CacheBackendProtocol
from lexigram.contracts.data import DatabaseProviderProtocol
from lexigram.contracts.security.secrets import SecretStoreProtocol

Key Modules

Key Source Files

Design Principles

• Zero dependencies — no third-party runtime imports
• Protocol-only — defines interfaces, never implementations
• Stable contract — all other Lexigram packages depend on this one; breaking changes are versioned