From d3a0bd80ee589beaae099b8e8dc150f846f6dca8 Mon Sep 17 00:00:00 2001 From: Eduardo Firvida Date: Mon, 16 Jun 2025 07:24:45 -0400 Subject: [PATCH 1/2] Fix create_response imports in cli --- papi/cli.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/papi/cli.py b/papi/cli.py index fdaa791..cee291c 100644 --- a/papi/cli.py +++ b/papi/cli.py @@ -43,7 +43,7 @@ from papi.core.exceptions import APIException from papi.core.init import init_base_system, init_mcp_server from papi.core.logger import logger, setup_logging -from papi.core.models.response import create_response +from papi.core.response import create_response from papi.core.settings import get_config __version__ = importlib.metadata.version("papi") From a554d718d32d0b9f3a859e9c05bcd725061ec088 Mon Sep 17 00:00:00 2001 From: Eduardo Firvida Date: Mon, 16 Jun 2025 08:21:38 -0400 Subject: [PATCH 2/2] Update Readmemd --- README.md | 369 ++++++++---------------------------------------------- 1 file changed, 53 insertions(+), 316 deletions(-) diff --git a/README.md b/README.md index 9324b0e..9f01e23 100644 --- a/README.md +++ b/README.md @@ -4,367 +4,104 @@ # pAPI โ€“ Python/Pluggable API Framework -**pAPI** (Python API / Pluggable API) is a modular micro-framework built on FastAPI, designed for creating composable, tool-oriented web APIs. It extends FastAPI's routing system with advanced capabilities for agent-based applications and modular service architectures. +**pAPI** is a modular micro-framework built on top of FastAPI for composing scalable, tool-oriented APIs. It extends FastAPIโ€™s routing system with native support for modular service architectures, addon discovery, and LLM tooling. -> ๐Ÿšง **Documentation Notice**: Full documentation is not yet available. This README serves as the primary reference until official documentation is released. - -![pAPI Architecture](https://via.placeholder.com/800x400?text=pAPI+Modular+Architecture) -*Example: pAPI modular architecture with core system and addons* +> ๐Ÿ“š **Documentation**: Full documentation is currently a work in progress (WIP). +> ๐Ÿ‘‰ [https://efirvida.github.io/pAPI/](https://efirvida.github.io/pAPI/) +> ๐Ÿงช Example addons are available in the [`extra_addons` branch](https://github.com/efirvida/pAPI/tree/extra_addons) --- ## โœจ Key Features -### ๐Ÿ”Œ Plug-and-Play Architecture - -- Dynamic endpoint registration using `RESTRouter` from `api.core.router` -- Addon dependency resolution and automatic initialization -- Route overriding support for behavior extension -- Discoverable module structure integration -- Fully compatible with FastAPI's async support and high performance - -### ๐Ÿง  Native MCP Integration +- ๐Ÿ”Œ **Plug-and-Play Architecture** + Modular addon system with automatic route discovery and dependency resolution. -```python -@app.get("/tool", expose_as_mcp_tool=True) -async def my_tool(): - return {"result": "tool output"} -``` +- ๐Ÿง  **LLM Tooling & MCP Integration** + Expose endpoints as tools for agent frameworks using SSE and standard response models. -- Transform any HTTP endpoint into MCP-compatible tool -- Automatic SSE endpoint exposure (`/sse`) +- ๐Ÿงฌ **Multi-Database Support** + Native support for MongoDB (Beanie), SQL databases (SQLAlchemy), and Redis. -Example of VSCode copilot agent configuration: +- ๐Ÿ“ฆ **Standardized API Responses** + Unified success/error format with automatic metadata injection and exception handling. -```json -{ - "name": "pAPI", - "type": "sse", - "url": "http://localhost:8000/sse" -} -``` +- โšก **Performance-Optimized** + Fully async, lazily loaded, and built on FastAPIโ€™s high-performance core. -### ๐Ÿงฌ Multi-Database Support +- ๐Ÿ› ๏ธ **Developer Tooling** + Extensible CLI system and async-enabled IPython shell for rapid development. -| Database | ODM/ORM | Use Case | -| -------- | ---------- | ------------------ | -| MongoDB | Beanie | Document storage | -| SQL DBs | SQLAlchemy | Relational data | -| Redis | aioredis | Caching & sessions | - -- Automatic model discovery at startup -- Connections only initialize when relevant models are found -- DB-agnostic design: bring your own database logic -- Transparent connection handling (no manual configuration needed) - -> ๐Ÿ’ก While the mixed-database architecture allows maximum flexibility, using multiple systems may increase complexity. The choice depends on your application's needs. +--- -### ๐Ÿ“ฆ Standardized API Responses +## ๐Ÿงฉ Addon System -```python -# Unified response structure -class APIResponse(BaseModel): - success: bool - message: Optional[str] - data: Optional[Any] - error: Optional[APIError] - meta: Meta +pAPI is built around a **composable addon architecture**, where each addon functions like a LEGOยฎ pieceโ€”self-contained, reusable, and designed to interlock with others. -# Example error handling -raise APIException( - status_code=status.HTTP_404_NOT_FOUND, - message="Resource not found", - code="RESOURCE_NOT_FOUND", - detail={"resource_id": 123} -) -``` +These addons can: -- Consistent error handling via `APIException` -- Automatic metadata injection -- Standardized success/error states across all endpoints +* Register API routes (`RESTRouter`) +* Define database models (Beanie or SQLAlchemy) +* Hook into startup processes (`AddonSetupHook`) +* Extend the CLI with custom commands -### โšก Performance Optimized +Together, they form a cohesive and scalable API system, enabling you to build robust, modular services by simply connecting or extending the building blocks your application needs. -- Fully async FastAPI-based engine -- Lazy initialization of components -- Zero-overhead modular structure +Addons are declared in `config.yaml`, allowing clean separation of concerns and easy configuration. -### ๐Ÿ› ๏ธ Developer Tooling +--- -```bash -papi_cli start webserver # Start web server -papi_cli start mcpserver # Start MCP server -papi_cli shell # Launch async IPython shell -``` +## ๐Ÿ“Š Use Cases -- Extensible CLI system. Addons can register custom CLI commands -- Async-enabled development shell with IPython, to handle models data. +- **AI Agent Tooling** + Build modular tools for LLMs and agents. ---- +- **Composable Microservices** + Create reusable, pluggable service components. -## ๐Ÿงฉ Addon System +- **Rapid API Prototyping** + Launch structured APIs quickly with standardized behavior. -### Architecture Overview - -``` -your_extra_addons_path/ # Custom functionality -core/ -โ””โ”€โ”€ base/ - โ”œโ”€โ”€ user_auth_system/ # RBAC+ABAC security - โ””โ”€โ”€ image_storage/ # Image processing -``` - -### Initialization Hook - -Addons implement `AddonSetupHook` for custom startup logic: - -```python -from api.core.addon import AddonSetupHook - -class Addon(AddonSetupHook): - async def run(self): - await initialize_things() -``` - -### Built-in Addons - -| Addon | Description | Technologies | -| ------------------ | ----------------------------------- | ------------------------- | -| `user_auth_system` | RBAC+ABAC security with permissions | Casbin, SQLAlchemy, Redis | -| `image_storage` | Image upload/optimization service | Beanie, Pillow | - -### Configuration Example (`config.yaml`) - -```yaml -addons: - extra_addons_path: "your_extra_addons_path" - enabled: - - user_auth_system - - image_storage - config: - user_auth_system: - allow_registration: true - security: - access_token_expire_minutes: 60 - secret_key: "secret_key" - image_storage: - image_optimization: - max_dimension: 2048 - jpeg_quality: 85 -``` +- **Security and Auth Systems** + Implement RBAC/ABAC policies using addon-based security modules. --- ## ๐Ÿš€ Getting Started -### Installation - ```bash -git clone https://github.com/your-repo/papi.git -cd papi +git clone https://github.com/efirvida/pAPI.git +cd pAPI rye sync -rye run python src/papi/papi_cli.py --help -``` - ---- - -## ๐Ÿ› ๏ธ Creating an Addon - -### 1. Addon Structure -Each addon must follow any python module structure, addons are python modules: -``` -your_addon/ -โ”œโ”€โ”€ __init__.py -โ”œโ”€โ”€ manifest.yaml -โ”œโ”€โ”€ models.py (optional) -โ”œโ”€โ”€ routers.py (optional) -โ””โ”€โ”€ any_other_files.py -``` - -### 2. Required manifest.yaml -Every addon must include a `manifest.yaml` file with at least these fields: - -```yaml -name: task_queue -version: 1.0.0 -description: Background task queue system using Celery -author: pAPI Team - -dependencies: - - user_auth_system # Other addons this depends on if addon is added as dependencies, the can be imported in the current addon - -python_dependencies: - - "APScheduler>=3.9.0" -``` - -### 3. Router Registration Example - -** adds routers.py or any PY file, the discover system will look for all `RESTRouter` instances and include them in the main router ** - -```python -# routers.py -from papi.core.router import RESTRouter - -api_router = RESTRouter() - -@api_router.get("/status") -async def status_check(): - return {"status": "OK"} -``` - -Then import in `__init__.py`: -```python -from .routers import api_router -``` - -### 4. Database Models -For Beanie (MongoDB) models: - -**models.py** -```python -from beanie import Document - -class Person(Document): - name: str - - class Settings: - name = "persons" # Collection name -``` - -The system will automatically: -- Discover models when imported in `__init__.py` by searching for beanie document clases, bases for SQL alchemy -- Initialize database connections -- Create collections/tables if needed - -### 5. A Complete Addon Example -**File structure:** -``` -weather_addon/ -โ”œโ”€โ”€ __init__.py -โ”œโ”€โ”€ manifest.yaml -โ”œโ”€โ”€ models.py -โ””โ”€โ”€ routers.py -``` - -**manifest.yaml:** -```yaml -name: weather -version: 1.0.0 -description: Weather data API -author: Your Name - -dependencies: - - user_auth_system - -python_dependencies: - - "requests>=2.28.0" -``` - -**models.py:** -```python -from beanie import Document - -class WeatherStation(Document): - name: str - location: dict - last_reading: float - - class Settings: - name = "weather_stations" -``` - -**routers.py:** -```python -from papi.core.router import RESTRouter -from papi.core.response import create_response - -# load user_auth_system tools from addons dependencies -from user_auth_system.security.dependencies import permission_required -from user_auth_system.security.enums import PolicyAction - -from .models import WeatherStation - -router = RESTRouter() - -@router.get("/stations", - dependencies=[permission_required(PolicyAction.READ, required_roles=["user"])], -) -async def list_stations(): - """ - Only authenticated user with role usr can access this endpoint - """ - stations = await WeatherStation.find_all().to_list() - return create_response(data=stations) -``` - -**__init__.py:** -```python -from .routers import router -from .models import WeatherStation - -__all__ = ["router"] # Explicit exports -``` - -> ๐Ÿ’ก **Pro Tip**: The addon system will automatically: -> - Discover and mount all routers -> - Initialize database models -> - Install Python dependencies -> - Verify addon dependencies -> - Run any `AddonSetupHook` implementations +rye run python papi/cli.py --help +```` --- -## ๐Ÿ“Š Use Cases +## ๐Ÿง  Learn More -1. **AI Agent Tooling** - Expose MCP-compatible tools for LLM agents with standard response formatting. +Check the documentation for: -2. **Modular Microservices** - Build independent, composable services with unified interfaces. +* Addon development +* CLI usage +* Response formatting +* Database integrations +* MCP/LLM support -3. **Workflow Automation** - Develop task-based APIs for orchestrated pipelines. - -4. **Rapid Prototyping** - Launch experiments quickly with self-contained addons. - ---- - -## ๐Ÿ“Š Architecture Diagram - -```mermaid -graph TD - A[FastAPI Core] --> B[RESTRouter] - B --> C[Addon System] - C --> D[user_auth_system] - C --> E[image_storage] - C --> F[Custom Addons] - A --> G[Database Layer] - G --> H[MongoDB] - G --> I[SQL Database] - G --> J[Redis] - A --> K[MCP Adapter] - K --> L[SSE Endpoint] - A --> M[Response Formatter] - M --> N[Standard APIResponse] - M --> O[APIException Handler] - A --> P[CLI System] - P --> Q[Addon Commands] - P --> R[pAPI Shell] -``` +๐Ÿ‘‰ [https://efirvida.github.io/pAPI/](https://efirvida.github.io/pAPI/) --- ## ๐Ÿค Contributing 1. Fork the repository -2. Create a feature branch (`git checkout -b feature/your-feature`) -3. Commit changes (`git commit -am 'Add feature'`) -4. Push branch (`git push origin feature/your-feature`) -5. Open a Pull Request +2. Create a feature branch (`git checkout -b feature/my-feature`) +3. Commit your changes +4. Push and open a Pull Request --- ## ๐Ÿชช License -MIT License ยฉ 2025 โ€” Eduardo Miguel Firvida Donestevez \ No newline at end of file +MIT License ยฉ 2025 โ€” Eduardo Miguel Firvida Donestevez +