Lexigram | Modern Python Framework

---

The Problem

Most Python frameworks let you write code freely — then spring surprises on you when things grow.

❌ 5000 lines of startup code
❌ Dependencies scattered everywhere
❌ Tight coupling hiding in plain sight
❌ No clear boundaries between components

Lexigram enforces the structure before you need it.

---

The Lexigram Way

You don’t wire dependencies by hand:

# ❌ Manual wiring — brittle at scale
service = UserService(PostgresRepo(), RedisCache())

You declare what you need:

# ✅ Declaration — the container wires it
class UserService:
    def __init__(self, repo: UserRepository, cache: Cache):
        ...

And the container resolves it:

service = await container.resolve(UserService)

Thats it. No globals. No magic. Just control.

---

Zero to Running

pip install lexigram lexigram-web

from lexigram import Application
from lexigram.web import WebProvider

app = Application(name="hello")
app.add_provider(WebProvider())

@app.controller()
class HelloController:
    @get("/hello")
    async def hello(self) -> dict:
        return {"message": "Hello, Lexigram"}

if __name__ == "__main__":
    app.run()

→ http://localhost:8000/hello

---

The Dependency Graph

graph TB
    subgraph "lexigram-contracts"
        C1[Protocols]
        C2[Types]
        C3[Exceptions]
    end
    subgraph "lexigram"
        M1[Module]
        M2[Provider]
        M3[Container]
    end
    subgraph "Extensions"
        E1[lexigram-web]
        E2[lexigram-ai-*]
        E3[lexigram-sql]
    end
    C1 & C2 & C3 --> M2
    M1 & M2 & M3 --> E1 & E2 & E3

Rules that make it work:

Rule	Why it matters
lexigram-contracts — zero deps	Contracts never pull in implementations
lexigram — only contracts	Core stays clean
Extensions — only core + contracts	Packages are truly pluggable

---

Why Teams Choose Lexigram

Type Safety That Scales

690+ mypy violations fixed. Full type inference on container operations. Your IDE knows what you have.

Async-Native

Everything is async by default. Sync code is the exception, not the rule. Built for Python 3.11+.

42 Packages, One Graph

Web, AI, SQL, events, tasks, auth, cache, search — all under one dependency hierarchy.

Lifecycle-Managed

Providers boot in dependency order. Connections open before use, close on shutdown. No more connection pool leaks.

---

Core Concepts

Provider

Encapsulate registration and initialization for a service group.

class DatabaseProvider(Provider):
    name = "database"
    priority = ProviderPriority.INFRASTRUCTURE

    async def register(self, container: ContainerRegistrarProtocol) -> None:
        container.singleton(DatabaseProtocol, PostgresDatabase)

    async def boot(self, container: BootContainerProtocol) -> None:
        db = await container.resolve(DatabaseProtocol)
        await db.connect()

Module

Composable, reusable service bundles.

from lexigram.di.module import module

@module(imports=[DatabaseProvider, CacheProvider])
class AppModule(Module):
    pass

Result

Explicit error handling without exceptions polluting call stacks.

result = await user_service.find(user_id)
if result.is_ok():
    user = result.unwrap()
else:
    return Err(result.unwrap_err())

Contract

Protocol-based boundaries that make swapping implementations trivial.

class CacheBackend(Protocol):
    async def get(self, key: str) -> bytes | None: ...
    async def set(self, key: str, value: bytes, ttl: int) -> None: ...

---

Get Started

pip install lexigram lexigram-web

from lexigram import Application
from lexigram.web import WebProvider

app = Application(name="my-app", config=Config.from_env())
app.add_provider(WebProvider())

if __name__ == "__main__":
    app.run()

---

Next Steps

Installation pip, uv, Docker. Pick your setup.

Core Concepts Providers, Modules, DI, Result pattern.

First App Build a working app step by step.

Project Structure Layouts from prototype to production.