Metadata-Version: 2.4
Name: bussdcc-framework
Version: 0.36.0
Summary: An opinionated runtime and tooling layer built on top of bussdcc.
Author-email: "Joshua B. Bussdieker" <jbussdieker@gmail.com>
Maintainer-email: "Joshua B. Bussdieker" <jbussdieker@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jbussdieker/bussdcc-framework
Project-URL: Documentation, https://github.com/jbussdieker/bussdcc-framework/blob/main/README.md
Project-URL: Repository, https://github.com/jbussdieker/bussdcc-framework
Project-URL: Issues, https://github.com/jbussdieker/bussdcc-framework/issues
Project-URL: Changelog, https://github.com/jbussdieker/bussdcc-framework/blob/main/CHANGELOG.md
Keywords: framework
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bussdcc~=0.40.0
Requires-Dist: flask~=3.1.3
Requires-Dist: flask-socketio~=5.6.1
Provides-Extra: sqlalchemy
Requires-Dist: flask-sqlalchemy~=3.1.1; extra == "sqlalchemy"
Requires-Dist: sqlalchemy~=2.0.48; extra == "sqlalchemy"
Provides-Extra: dev
Requires-Dist: types-Flask-SocketIO; extra == "dev"
Dynamic: license-file

# BussDCC Framework

**bussdcc-framework** is an opinionated runtime and tooling layer built on top of `bussdcc`.

It provides the components most real systems need:

* runtime orchestration
* event sinks and replay
* JSONL event logging
* a lightweight web interface
* system identity discovery
* deterministic replay of recorded event streams

The framework keeps the **bussdcc kernel small** while providing a practical foundation for building complete systems.

# Architecture

```
Application
    ↓
bussdcc-framework
    ↓
bussdcc
```

### bussdcc (kernel)

The core provides the minimal primitives:

* messages
* events
* processes
* services
* runtime
* state
* clocks
* event buses

### bussdcc-framework

The framework adds system-level capabilities:

* structured event logging
* replay runtime
* web interface
* event sinks
* operational services
* application scaffolding

# Features

## Runtime

Extended runtime with event sinks and framework lifecycle messages.

```python
from bussdcc_framework.runtime import Runtime

runtime = Runtime()
```

Features:

* event sink pipeline
* framework lifecycle messages
* graceful shutdown handling
* replay support

## Event Logging (JSONL)

Built-in JSONL logging for deterministic replay and auditing.

```python
from bussdcc_framework.io.jsonl import JsonlSink

runtime.add_sink(JsonlSink("./events"))
```

Logs are segmented by time:

```
events/
  2026-03-09/
    12-00-00.jsonl
    12-10-00.jsonl
```

Each line contains a structured event:

```json
{
  "time":"2026-03-09T12:00:01.735301+00:00",
  "type":"bussdcc_framework.message.system:SystemIdentityEvent",
  "data":{ ... }
}
```

## Event Replay

Replay previously recorded event streams.

```python
from bussdcc_framework.runtime import ReplayRuntime
from bussdcc_framework.io.jsonl import JsonlSource

runtime = ReplayRuntime(speed=1.0)

runtime.add_source(JsonlSource("./events"))
```

This allows:

* deterministic testing
* system simulation
* historical debugging

## Web Interface

A lightweight Flask + Socket.IO interface for system control and monitoring.

```python
from bussdcc_framework.interface.web import WebInterface

runtime.add_process(
    WebInterface(host="0.0.0.0", port=5000)
)
```

Custom routes can be registered:

```python
class MyWeb(WebInterface):

    def register_routes(self, app, ctx):

        @app.route("/")
        def index():
            return "Hello World"
```

Inside Flask routes you can emit BussDCC messages:

```python
from bussdcc_framework.interface.web import emit

emit(MyMessage())
```

## Console Logging

Simple JSON event output for development.

```python
from bussdcc_framework.io.console import ConsoleSink

runtime.add_sink(ConsoleSink())
```

Example output:

```

{"time":"2026-03-09T12:00:01.722504+00:00","type":"bussdcc_framework.message.framework:FrameworkBooted","data":{"version":"0.1.0"}}
```

## System Identity Service

Discovers system metadata at runtime:

* hostname
* hardware model
* CPU serial

```python
from bussdcc_framework.service import SystemIdentityService

runtime.add_service(SystemIdentityService())
```

This emits a `SystemIdentityEvent` and stores it in runtime state.

# Example

Minimal application:

```python
from bussdcc_framework.runtime import Runtime
from bussdcc_framework.io.console import ConsoleSink
from bussdcc_framework.service import SystemIdentityService

runtime = Runtime()

runtime.add_sink(ConsoleSink())
runtime.add_service(SystemIdentityService())

runtime.boot()
runtime.run()
```

# Design Goals

### Deterministic systems

All behavior flows through events that can be logged and replayed.

### Strong typing

All messages are typed dataclasses.

### Operational visibility

Event streams are easily captured and analyzed.

### Replayable execution

Recorded systems can be replayed exactly for debugging and simulation.

### Small core

The `bussdcc` kernel stays minimal while the framework provides practical tooling.

# Installation

```bash
pip install bussdcc-framework
```

# Related Projects

* **bussdcc** – event-driven systems kernel
* **bussdcc-hardware** – hardware device integrations

# License

MIT License
