SignalPy Kernel

A reactive component kernel for backend services

The Idea

Frontend frameworks like Vue and React changed how UIs work: you declare what depends on what, and when data changes, the framework updates everything automatically. No manual callbacks. No stale state.

SignalPy brings this model to backend services.

Your components declare dependencies. The kernel wraps every injected service in a reactive Signal. When you read self.rt.config inside an @effect, the kernel tracks that read. When config changes, your effect re-runs automatically.

from signalpy.kernel import component, requires, computed, effect, runnable
from signalpy.kernel.contracts import IConfig

@component("greeter")
@requires(config=IConfig)
class Greeter:

    @computed                                        # cached, auto-recomputes
    def greeting(self):
        return self.rt.config.get("greeting", "Hello")

    @effect                                          # re-runs when deps change
    def log_greeting(self):
        print(f"Greeting is now: {self.greeting()}")

    @runnable("greet", params=GreetParams, description="Greet someone")
    async def greet(self, params):
        return {"message": f"{self.greeting()}, {params.name}!"}

Where to Start

Pick based on what you need right now:

Your goal	Start here
“What APIs do I use? Where do I put my code?”	Layer Rules & Decision Guide — the most important page
“I want to build something with this”	Tutorials 1–7, in order
“I want to understand how it works”	Reactivity by Example → Reactive Internals
“I want to read the source code”	Source Walkthrough — all 9 files, dependency order
“I need to look up a specific API”	Reference section below

Tutorials

Each builds on the last. Read in order.

#	Tutorial	What you’ll learn
0	Layer Rules & Decision Guide	Three orthogonal mechanisms: `@requires` + direct calls, `@runnable` + transports, `publish` / `@subscribe`
1	First Component	`@component`, `@lifecycle`, boot, shutdown
2	Give and Take	`@provides`, `@requires`, typed contracts, `self.rt`
3	Dynamic Services & Reactivity	`list[C]` aggregate, `@effect`, `@computed`, `batch()`, hot-add/remove
4	Runnables & Transport Config	`@runnable` schema declarations, `transports=[]`, transport config on `@component`
5	Transport Adapters	How REST/MCP/CLI bindings are generated from `kernel.runnables()`
6	Auth & Policy	`requires_action`, `requires_role`, per-consumer auth enforcement
7	Building a Provider	Write your own ICache, swap implementations

Concepts

Deep dives. Read any of these independently.

Page	What it explains
Architecture	Constitution, two-axis model, three orthogonal mechanisms
Reactivity by Example	One full reactive cycle: boot → first run → mutation → re-run (side-by-side)
Reactive Engine Internals	The 5 data structures, tracking mechanism, 3 worked scenarios
Threading & Async Model	Concurrency, async supersede, `is_stale()`, `cancel_on_supersede`, propagation algorithm
Supervision & Reliability	Erlang-style supervision trees, dead letter channel
Bridging External Systems	Bridge pattern: lifecycle, 90% surface, escape hatch
Deployment Scales	Monolith → containers → Dapr → agent system
Source Walkthrough	All 9 kernel files explained in dependency order (reference companion)

Production Patterns

Each pattern is a standalone recipe using only standard kernel APIs.

Pattern	What it demonstrates
Reactive Intent vs Default	7 escape hatches for when default reactive semantics don’t fit
Secret Rotation	Config → provider → @effect → vault auto-rotates
A/B Testing	Deterministic hashing, map injection, runtime split adjustment
Multi-Tenant Isolation	kernel.instantiate(), target routing, structural scoping
Extension Bundle	hot_add/remove as a plugin system
Circuit Breaker	Signal for breaker state, @effect for transitions
Audit Trail	@subscribe wildcards for cross-cutting compliance
Unit Testing	Three strategies: minimal kernel, reactive testing, event testing
Hot Code Update	Blue-green replacement with snapshot/restore

Reference

Page	What’s in it
Traits (L0–L3)	23 traits — what each is, how the kernel infers it
Decorators	All 11 decorators – signature, parameters, example
Contracts	8 Protocol interfaces — methods, providers, `self.rt.*` access
Kernel API	`Kernel`, `ServiceRegistry`, `Bus`, `Runtime`, `Signal`/`Computed`/`Effect`

The 11 Decorators

@component  @provides  @requires           # core
@computed   @effect                         # reactive
@lifecycle.activate/deactivate/health       # lifecycle
@runnable                                   # surface (schema-only)
@prop   @kind   @skill                      # metadata
@subscribe                                  # events

At a Glance

Kernel core	~3,800 lines, 9 files, zero required dependencies
Reactivity	Signal, Computed, Effect — Vue 3-style auto-tracking
Reliability	Dead letter, supervision trees
Providers	9: config, logging, credentials, storage, auth, tracing, workspace, gateway, configadmin
Adapters	3: REST (FastAPI), MCP, CLI (Click)
Tests	335
Traits	24 across 4 levels (L0 Kernel, L1 Platform, L2 App, L3 Instance)