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-lib

The import name is neuronos_capabilities (from neuronos_capabilities import ...).

Moved from neuronos-capabilities. Versions up to 0.0.1.5 were published as neuronos-capabilities; from 0.0.2 on the package is neuronos-capabilities-lib. The code and imports are the same. Before switching a local environment, run pip uninstall neuronos-capabilities (both names install the same neuronos_capabilities/ folder).

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

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": "alice@example.com"})
    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