Tyler King
89a054d656
Python SDK for shellbound Django applications. Provides ShellApp, ShardContext, ShellboundMiddleware. Emits Chronicle events to stdout in dev mode. Includes fix for IndexError in apps.py when DJANGO_SETTINGS_MODULE has no dots (e.g. instance_settings). Shard name now falls back safely without eager default argument parsing. Implements SHELLBOUND-APP-0001 §4 (dev mode). Wired into entropyopposition as of 2026-03-18.
68 lines
1.8 KiB
Markdown
68 lines
1.8 KiB
Markdown
# substrate-sdk-python
|
|
|
|
Build shellbound applications. Any Python framework. Any deployment. Trust rooted in hardware.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pip install substrate-sdk[django]
|
|
```
|
|
|
|
## Django (2 lines)
|
|
|
|
```python
|
|
# settings.py
|
|
INSTALLED_APPS = [
|
|
...
|
|
'substrate_sdk.django',
|
|
]
|
|
MIDDLEWARE = [
|
|
...
|
|
'substrate_sdk.django.ShellboundMiddleware',
|
|
]
|
|
```
|
|
|
|
Every request is Chronicle-attributed. Every model save is Chronicle-recorded.
|
|
If a bascule shell is present: fully governed. If not: development mode, works normally.
|
|
|
|
## Direct usage
|
|
|
|
```python
|
|
from substrate_sdk import ShellApp
|
|
|
|
app = ShellApp(shard_name="my-app", capabilities={"network": True})
|
|
context = app.register()
|
|
print(context.is_governed) # True if shell present
|
|
print(context.shard_did) # DID assigned by shell
|
|
```
|
|
|
|
## What this does
|
|
|
|
When running inside a Substrate FFC:
|
|
- Your process gets a DID + SPIFFE SVID
|
|
- Your process gets a governed accord
|
|
- Every request is Chronicle-attributed
|
|
- Every operation is audit-verifiable
|
|
- You participate in the governance fabric
|
|
|
|
When running locally (no shell):
|
|
- Development mode — everything works normally
|
|
- Chronicle events go to stdout
|
|
- No governance enforcement
|
|
- Zero impact on application behavior
|
|
|
|
## Phase B: HFL Direct Binding (planned)
|
|
|
|
When the HFL kernel module is present, `substrate_sdk` will route Chronicle
|
|
events through `substrate-hfl-python` (PyO3) instead of stdout. This upgrades
|
|
a Tier 4 deployment to Tier 1/2 with **zero application code changes**.
|
|
|
|
```
|
|
Phase A (current): SDK → stdout → bascule-filter → Chronicle
|
|
Phase B (planned): SDK → substrate-hfl-python (PyO3) → HFL → Chronicle
|
|
```
|
|
|
|
`substrate-hfl-python` is a new crate in the substrate workspace:
|
|
- Depends on `hfl-types`
|
|
- Exposes: `chronicle_write()`, `accord_check()`, `session_get()`
|
|
- `substrate_sdk/chronicle.py` detects HFL availability and routes automatically
|