Contracts, not coupling
Every package talks through protocols in oridecon-contracts. Agents code to interfaces, not implementations. Swap Redis for in-memory, Postgres for SQLite — same contract, one config line.
v0.1 alpha Python 3.11+ · MIT licensed
The AI-friendly Python framework
Contracts and protocols coding agents can reason about. 17 AI packages they can build with. A full backend — web, SQL, auth, queues — wired through one container.
uv add oridecon-cli pip install oridecon-cli · coding agents app.py
# composition root — oridecon run boots this
from oridecon import Application, OrideconConfig
from oridecon.web import WebModule
from oridecon.sql import DatabaseModule
from oridecon.cache import CacheModule
from oridecon.ai import AIModule
def create_app(
config: OrideconConfig | None = None
) -> Application:
app = Application(
name="my-app",
config=config,
)
app.add_modules([
DatabaseModule.configure(),
CacheModule.configure(),
AIModule.configure(),
WebModule.configure(
discover=["my_app.controllers"],
),
])
return app
app = create_app() Provider · INFRASTRUCTURE DatabaseProvider
Provider · INFRASTRUCTURE CacheProvider
Module · AI AIModule
Provider · PRESENTATION WebProvider
Application · ready 0.42s · 4 providers
0.1.1 version
100+ protocols
17 AI packages
3.11+ Python
MIT license
How it feels
A support agent, in four files
A @tool, AgentBuilder, a provider that binds LLMClientProtocol, then create_app().
The executor returns Result. The model is a YAML (or test fake) swap — not a rewrite.
# @tool wraps a plain async function for the ReAct loop
from oridecon.ai.agents import tool
@tool(description="Look up an order by ID and return status.")
async def lookup_order(order_id: str) -> dict:
return {"found": True, "order_id": order_id, "status": "shipped"}# AgentBuilder freezes config; the facade returns Result
from oridecon.ai.agents import AgentBuilder
from oridecon.contracts.ai.agents import (
AgentError, AgentExecutorProtocol, AgentProtocol, AgentResponse,
)
from oridecon.result import Result
def build_support_agent() -> AgentProtocol:
return (
AgentBuilder("support-agent")
.with_system_prompt("Use tools. Never invent order state.")
.with_tools(lookup_order)
.with_strategy("react")
.build()
)
class SupportAgent:
def __init__(self, executor: AgentExecutorProtocol, agent: AgentProtocol) -> None:
self._executor = executor
self._agent = agent
async def ask(self, question: str) -> Result[AgentResponse, AgentError]:
return await self._executor.run(agent=self._agent, message=question)# bind LLMClientProtocol in register() — AgentsModule resolves it at boot
from oridecon.di.provider import Provider
from oridecon.contracts.ai.llm import LLMClientProtocol
from oridecon.contracts.ai.agents import AgentExecutorProtocol
from oridecon.contracts.core.di import ContainerRegistrarProtocol, ContainerResolverProtocol
class AgentSupportProvider(Provider):
name = "agent-support"
async def register(self, container: ContainerRegistrarProtocol) -> None:
container.singleton(LLMClientProtocol, factory=self._llm)
async def boot(self, container: ContainerResolverProtocol) -> None:
executor = await container.resolve(AgentExecutorProtocol)
self._support = SupportAgent(
executor=executor,
agent=build_support_agent(),
)# composition root — list the modules this app actually uses
from oridecon import Application, OrideconConfig
from oridecon.ai.agents import AgentConfig, AgentsModule
from oridecon.web import WebModule
def create_app(config: OrideconConfig | None = None) -> Application:
app = Application(name="support-agent", config=config)
app.add_modules([
AgentsModule.configure(AgentConfig(max_iterations=5)),
WebModule.configure(discover=["support_agent.controllers"]),
])
app.add_providers([AgentSupportProvider()])
return appThe stack
Built so agents don’t guess
The same seams that keep a human codebase composable are the ones a coding agent can inspect, type-check, and test against.
Providers with a boot order
Lifecycle and wiring live in one place. Register, boot, shut down. Priority is explicit — web mounts last, after SQL, cache, and auth are actually ready.
Result, not exceptions
Domain failures are Ok / Err. Agents can follow the error path without guessing which exception flies out of a handler.
Import linter
Architectural boundaries are enforced. Cross-package leaks fail CI before they ship — agents can verify their own imports.
Web & OpenAPI
ASGI controllers, routing, middleware, CORS, rate limiting. Docs generate themselves at /docs.
Typed end to end
Python 3.11+, 100% async, full type hints. Your IDE and your agent see the same signatures.
AI native
Designed for coding agents, not just humans
Oridecon is a Python backend an LLM can actually operate: stable contracts, an explicit boot graph, and docs that ship in the format agents already fetch.
Playbook
How agents should learn the tree
Read order, repo map, one project layout (domains/, di/), fail vs fix, and /SKILL.md. Machine indexes: /llms.txt, /agents.md, /llms/oridecon-sql.txt.
ProtocolsInterfaces they can inspect
100+ protocols, 533 error codes, typed providers. Agents reason about contracts instead of scraping READMEs for hidden kwargs.
SkillsDrop-in agent skills
Public pack at github.com/dbtinoy-/oridecon-skills — Claude Code, Cursor, OpenCode. One-file fetch: /SKILL.md.
Ecosystem
Install only what you use
Every extension depends on oridecon and oridecon-contracts — never on each other. The boundary is what keeps the graph composable.
Foundation
Application, container, providers, modules, config, Result.
Web & HTTP
ASGI, GraphQL, outbound HTTP, webhooks.
Data
SQL, NoSQL, cache, object storage, search.
Security
Auth, secrets, JWT, OAuth2, guards.
Events
Domain events, queues, notifications.
Infrastructure
Tasks, workflows, tenancy, resilience, vectors.
AI platform
LLMs, RAG, agents, memory, MCP, skills, eval.
Multimedia
Image, video, audio, TTS, upscale, interpolate.
Tooling
CLI, testing, admin, UI — experimental except testing.
Examples
Working apps, not snippets
Each one boots the real Application — providers, DI, the web stack. In-memory backends, so the run is deterministic.
Support Agent
A ReAct agent with tools on the container.
OpenAuth Web
Cookie sessions, JWT, lockout after five failures.
OpenEvent-Driven Orders
CQRS orders, domain events, a transactional outbox.
OpenSQL Repository
SQL in the repository. The controller stays thin.
OpenComing from FastAPI
Keep the HTTP instincts. Add a composition root.
Starlette routing, Pydantic request shapes, OpenAPI — you already know this layer. Oridecon wraps it in a container, providers, and a contract-first ecosystem so SQL, cache, auth, queues, and AI feel as designed as the routes. Feature types live in domains/, not a models/ directory.
FastAPI Oridecon
What it is A focused web framework — routes, OpenAPI, Pydantic That HTTP layer plus the rest of the application
Dependencies Depends() on the path operation The same idea, on the constructor
Lifecycle Startup and shutdown hooks on the app Providers: register, boot, shutdown
Backends You pick and import the client Protocols in oridecon-contracts; swap in config
Expected errors HTTPException at the handler Result[T, E] in the domain, HTTP at the edge
FAQ
Questions agents (and humans) ask
What is Oridecon?
Oridecon is an async-first, contract-driven Python application framework. The core gives you a DI container, providers, modules, YAML config, and the Result type. Extensions add web, SQL, auth, queues, and a 17-package AI platform — each talking through protocols, never through each other.
I already use FastAPI. Will I feel lost?
No. Starlette routing, Pydantic request shapes, and OpenAPI are still the HTTP layer. Oridecon puts a composition root around them: constructor injection instead of Depends() on the handler, providers instead of ad-hoc startup hooks, and oridecon-contracts so you can swap SQL, cache, or LLM backends in config. Adopt it one service at a time. See the FastAPI map.
Why call it AI-friendly?
Coding agents need stable interfaces, typed errors, and docs they can load. Oridecon ships 100+ protocols, 533 error codes, /llms.txt, /agents.md, /SKILL.md, a public oridecon-skills pack, runnable examples, and fail vs fix. Import boundaries are linted so generated code cannot quietly couple packages.
What Python versions are supported?
Python 3.11 or newer. The stack is 100% async/await. Install with uv add oridecon-cli (recommended) or pip install oridecon-cli, then oridecon new project my-app --template web-api.
Is Oridecon production-ready?
Oridecon is alpha (0.1.x). Public APIs may change before 1.0. Pin versions in production, follow the changelog, and treat it as early on purpose — the architecture is stable; the surface is still moving.
Do I have to install all 54 packages?
No. Scaffold with uv add oridecon-cli, then oridecon new project my-app --template web-api. The foundation is oridecon plus oridecon-contracts. Add oridecon-web, oridecon-sql, oridecon-ai-llm, or anything else only when you need it. Extensions never depend on other extensions.
Updates
What’s new
The 0.1.1 line, plus writing from the last few weeks. Not a git log.
0.1.1 Public 0.1 line on PyPI. Pin the alpha range in production. Container and providers `register()` binds. `boot()` resolves. The two never share a method. Result for the domain User-not-found is a value. The database dying still raises. Contracts only Extensions depend on `oridecon` and `oridecon-contracts`, never on each other. One project tree `domains/` for features, app-root `di/` for providers. Templates add packages, not a second shape. Agents can read it `/llms.txt`, `/agents.md`, and `/SKILL.md` are the operating manual.
Blog
Alpha 0.1.x — what is stable
The architecture is the pin. Package names and experimental surfaces will still move. Here is what we will not casually rewrite.
Sep 6, 2026
BlogHow coding agents should read Oridecon
The shortest path from a fresh clone to a change that will pass the import linter — llms.txt, agents.md, contracts, then an example.
Sep 1, 2026
BlogComing from FastAPI
FastAPI is a great HTTP layer. Oridecon keeps that instinct and puts a composition root around it — you are not starting over.
Aug 26, 2026
Start building
Ship a backend your agent can keep working on
Install the CLI, scaffold with oridecon new project, and add packages as you need them. The contracts stay put.
uv add oridecon-cli