Pico Ecosystem¶

The Pico framework consists of multiple packages that work together seamlessly.

Architecture Overview¶

┌─────────────────────────────────────────────────────────────────┐
│                        Your Application                         │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         pico-boot                              │
│              Zero-configuration bootstrap layer                  │
│         (auto-discovery, scanner harvesting)                    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                          pico-ioc                               │
│                   Core DI Container Engine                       │
│    (components, factories, scopes, AOP, event bus, config)      │
└─────────────────────────────┬───────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│   pico-fastapi  │ │ pico-sqlalchemy │ │   pico-celery   │
│                 │ │                 │ │                 │
│  FastAPI routes │ │  SQLAlchemy ORM │ │  Celery tasks   │
│  & middleware   │ │  & sessions     │ │  & workers      │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │                                       │
          ▼                                       ▼
┌─────────────────┐                     ┌─────────────────┐
│  pico-pydantic  │                     │   pico-agent    │
│                 │                     │                 │
│   Validation    │                     │   LLM agents    │
│  interceptors   │                     │   & tools       │
└─────────────────┘                     └─────────────────┘

Core Packages¶

pico-ioc¶

The foundation of the ecosystem. A lightweight, async-native dependency injection container.

Features: - Decorator-based component registration (@component, @provides, @factory) - Unified configuration binding (@configured) - Multiple scopes (singleton, prototype, request, session) - AOP interceptors (@intercepted_by) - Async-native (__ainit__, aget(), ashutdown()) - Event bus for decoupled communication - Health checks and observability

Installation:

pip install pico-ioc
pip install pico-ioc[yaml]  # For YAML config support

pico-boot¶

Zero-configuration bootstrap layer. Recommended for applications.

Features: - Auto-discovery of plugins via entry points - Custom scanner harvesting - Drop-in replacement for pico_ioc.init()

Installation:

pip install pico-boot

Integration Packages¶

pico-fastapi¶

FastAPI integration with automatic dependency injection in routes.

Features: - Automatic injection in route handlers - Request-scoped dependencies - Middleware integration - Lifespan management

Usage:

from fastapi import FastAPI
from pico_boot import init
from pico_fastapi import PicoFastAPI

app = FastAPI()
container = init(modules=["myapp"])
pico = PicoFastAPI(container)
pico.install(app)

@app.get("/")
def index(service: MyService):  # Injected automatically
    return service.get_data()

pico-sqlalchemy¶

SQLAlchemy integration with session management.

Features: - Engine and session factory providers - Request-scoped sessions - Transaction management - Async engine support

Configuration:

database:
  url: postgresql://user:pass@localhost/db
  pool_size: 5
  echo: false

pico-celery¶

Celery integration for background tasks.

Features: - Task registration with DI - Worker container management - Result backend configuration

Configuration:

celery:
  broker_url: redis://localhost:6379/0
  result_backend: redis://localhost:6379/1

pico-pydantic¶

Pydantic validation via AOP interceptors.

Features: - Automatic input validation - Output serialization - Error formatting

Usage:

from pico_ioc import component, intercepted_by
from pico_pydantic import ValidationInterceptor

@component
class UserService:
    @intercepted_by(ValidationInterceptor)
    def create_user(self, data: CreateUserRequest) -> UserResponse:
        # data is validated automatically
        pass

pico-agent¶

LLM agent framework with dependency injection.

Features: - Declarative agent definitions with @agent and @tool - Multiple LLM backends (OpenAI, Gemini, LangChain) - Agent capabilities (memory, structured output, streaming) - Virtual and proxy agent patterns

Usage:

from pico_agent import agent, tool, AgentType

@agent(type=AgentType.OPENAI)
class AssistantAgent:
    system_prompt = "You are a helpful assistant."

@tool
def search(query: str) -> str:
    return f"Results for {query}"

Version Compatibility¶

Quick Start: Full Stack¶

Install everything:

pip install pico-boot pico-fastapi pico-sqlalchemy pico-pydantic

Create application.yaml:

app:
  name: My Application
  debug: false

database:
  url: postgresql://localhost/myapp
  pool_size: 10

Create your application:

# main.py
from fastapi import FastAPI
from pico_boot import init
from pico_fastapi import PicoFastAPI
from pico_ioc import component
from sqlalchemy.orm import Session

@component
class UserRepository:
    def __init__(self, session: Session):
        self.session = session

    def get_all(self):
        return self.session.query(User).all()

app = FastAPI()
container = init(modules=[__name__])
PicoFastAPI(container).install(app)

@app.get("/users")
def list_users(repo: UserRepository):
    return repo.get_all()

Run:

uvicorn main:app --reload

All integrations are loaded automatically!

Creating Your Own Integration¶

See Creating Plugins for a complete guide on building your own Pico-Boot integration.

Key steps:

1. Add entry point to pyproject.toml:

   [project.entry-points."pico_boot.modules"]
   my_integration = "my_integration"
   

2. Define configuration with @configured

3. Create components with @component
4. Provide third-party types with @provides
5. Publish to PyPI