lexigram-contracts 0.1.1

Core types and protocols for the Lexigram Framework

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.

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.contracts.domain.base import Entity, ValueObject
from lexigram.contracts.domain.aggregates 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.cache import CacheBackend
from lexigram.contracts.data import DatabaseProviderProtocol
from lexigram.contracts.security.secrets import SecretStoreProtocol

Key Modules

Module	What it contains
lexigram.result	Result[T, E], Ok, Err, ok(), err()
lexigram.contracts.core.container	ContainerRegistrarImpl, ContainerResolverImpl
lexigram.contracts.core.provider	Provider, ProviderPriority
lexigram.contracts.core.registry	Registry for type-keyed dispatch
lexigram.contracts.domain.base	Entity, ValueObject
lexigram.contracts.domain.aggregates	AggregateRoot
lexigram.contracts.domain.events	DomainEvent
lexigram.contracts.cache	CacheBackend protocol
lexigram.contracts.data	DatabaseProviderProtocol
lexigram.contracts.security.secrets	SecretStoreProtocol
lexigram.contracts.exceptions	LexigramError, full error hierarchy

Key Source Files

File	What it contains
src/lexigram/contracts/__init__.py	Lazy-loading re-exports of all public types
src/lexigram/result/	Result type and Ok/Err helpers
src/lexigram/contracts/domain/	Entity, ValueObject, AggregateRoot, DomainEvent
src/lexigram/contracts/core/	Container, Provider, Registry protocols
src/lexigram/contracts/exceptions/	LexigramError and domain error hierarchies

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