neuronos-capabilities 0.0.1.3

NeuronOS Python Capabilities Library - Provider-agnostic backend capabilities following hexagonal architecture

NeuronOS Capabilities Library

A collection of provider-agnostic backend capabilities for Python applications, following hexagonal architecture principles.

Each capability exposes well-defined ports and adapters, making implementations swappable without changing your application code.

Installation

pip install neuronos-capabilities

What is a Capability?

A capability is a self-contained backend module that follows hexagonal architecture (ports and adapters pattern):

Capability/
├── ports/              # Abstract interfaces — defines WHAT operations exist
├── adapters/           # Provider implementations — defines HOW they work
├── config/             # Configuration management
├── exceptions/         # Custom exception hierarchy
└── [name]_manager.py   # Public API — single entrypoint for consumers

You interact only with the Manager. The port defines the contract, and adapters implement it for specific providers. Switching from PostgreSQL to MySQL, or from Clerk to Auth0, is just a config change.

Available Capabilities

Capability	Description	Providers	Docs
SQLManager	Database management with ORM, migrations, connection pooling	PostgreSQL	docs/sql-manager.md
AuthManager	JWT authentication and role-based authorization for FastAPI	Clerk	docs/auth-manager.md
S3Manager	Object storage with CRUD, listing, multipart uploads, presigned URLs	AWS S3	docs/s3-manager.md

SQLManager — Quick Look

from neuronos_capabilities import SQLManager

config = {"host": "localhost", "database": "myapp", "user": "postgres", "password": "secret"}

with SQLManager(config) as db:
    db.create_tables([User])
    user = db.insert(User, {"name": "Alice", "email": "[e-mail]"})
    users = db.query(User, {"name": "Alice"})

AuthManager — Quick Look

from neuronos_capabilities import AuthManager
from fastapi import FastAPI, Depends

auth = AuthManager()  # reads NEURONOS_AUTH_JWKS_URL from env

app = FastAPI()

@app.get("/api/protected")
async def protected(user: dict = Depends(auth.require_auth())):
    return {"user_id": user["sub"]}

@app.get("/api/admin")
async def admin(user: dict = Depends(auth.require_roles(["org:admin"]))):
    return {"message": "Admin access granted"}

S3Manager — Quick Look

from neuronos_capabilities import S3Manager

s3 = S3Manager({"region": "us-east-1"})

# Upload and download
s3.put_object("my-bucket", "hello.txt", b"Hello World")
s3.download_file("my-bucket", "hello.txt", "/tmp/hello.txt")

# Generate a temporary download link
url = s3.generate_presigned_download_url("my-bucket", "hello.txt", expiration=900)

# Recursive listing
for obj in s3.walk("my-bucket", "data/"):
    print(f"{obj['Key']}  {obj['Size']} bytes")

# Multipart upload for large files
upload_id = s3.create_multipart_upload("my-bucket", "large-file.bin")
part = s3.upload_part("my-bucket", "large-file.bin", 1, upload_id, chunk)
s3.complete_multipart_upload("my-bucket", "large-file.bin", upload_id, [part])

Development

git clone https://github.com/neuronos/neuronos_python_capabilities_library
cd neuronos_python_capabilities_library
pip install -e ".[dev]"

pytest -v
pytest --cov=neuronos_capabilities --cov-report=html

Contributing

1. Follow hexagonal architecture: port → adapter → manager
2. Implement both sync and async methods
3. Include tests and documentation
4. Update this README with the new capability

License

MIT — see LICENSE