# 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

```bash
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](./docs/sql-manager.md) |
| **AuthManager** | JWT authentication and role-based authorization for FastAPI | Clerk | [docs/auth-manager.md](./docs/auth-manager.md) |
| **S3Manager** | Object storage with CRUD, listing, multipart uploads, presigned URLs | AWS S3 | [docs/s3-manager.md](./docs/s3-manager.md) |

### SQLManager — Quick Look

```python
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

```python
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

```python
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

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

```bash
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](./LICENSE)
