loom-kernel documentation

           

Framework-agnostic toolkit to build backend applications with typed use cases, repository contracts, and transport adapters.

Official hosted documentation: loom-py.readthedocs.io. Companion demo application: dummy-loom.

Overview

• Project Overview
  • At a glance
  • REST
  • ETL
  • Streaming
  • How the parts fit together
  • Streaming in practice
  • Documentation structure

Getting Started

• REST Quickstart
  • Install
  • 60-second demo: full CRUD from a model
  • Add business logic
  • Scope resources under a parent
  • Structured queries
  • Background jobs
  • Dispatch jobs from use cases + callbacks
  • Chain use cases (workflow pattern)
  • Declare REST interfaces
  • Bootstrap with YAML
  • Rules + Computes (advanced)
  • Next steps
• ETL Quickstart
  • Install
  • Minimal pipeline
  • Basic write modes
  • YAML config
  • File aliases
  • Next steps
• Streaming Quickstart
  • Install
  • Minimal flow
  • Run it
  • Public imports

REST

• Auto-CRUD
  • Minimal example
  • Restrict which routes are generated
  • Multiple read profiles
  • Mix auto-CRUD with custom routes
  • Bootstrap
  • When to add explicit use cases
  • Full working example
• Use-case DSL
  • Anatomy of a use case
  • Commands
  • F — typed field reference
  • Input markers
  • Agent marker — reaching a named agent
  • What the Agent() marker refuses
  • Mcp marker — reaching an MCP server directly
  • What the Mcp() marker refuses
  • Compute — derive and normalise fields
  • Rule — validate before execute
  • Predicate composition
  • Full use case example — update with all DSL features
  • Declaring use cases on a REST interface
  • Declaring routes in configuration (app.rest.interfaces)
  • Cross-use-case calls with ApplicationInvoker
  • Execution lifecycle
  • DSL quick-reference
• Caller identity and authorization
  • The identity
  • Reading the caller from a use case
  • Route-level roles
  • Configuring authentication
  • Request limits and CORS
  • Identity in jobs
  • Testing
  • Migrating from jwt_claims
• Role-based authorization
  • The model
  • Scopes are paths
  • Declaring roles
  • Deciding
  • Time-bound grants
  • Nobody grants more than they hold
  • Where grants come from
  • Roles as data
  • Custom roles
  • The product declaration
  • Elevating a write scope
• Postgres row-level security
  • The provider
  • Row-scoped tables
  • Threat model
  • Out of scope
  • Product obligations
  • Testing it
• Celery worker
  • Install
  • Core concepts
  • Define a job
  • Dispatch a job
  • Run a job inline
  • Callbacks
  • Post-commit failures
  • YAML configuration reference
  • Worker bootstrap
  • Callbacks and ApplicationInvoker — how it works
  • Start the worker
  • Integration tests
  • Docker-compose stack
• SQL API (ClickHouse)
  • Install
  • Configuration
  • The REST endpoint
  • Role model and grants
  • Several roles in one query
  • Threat model
  • Hardening
  • Authentication
• Persistence backends
  • Writing a backend
  • Capabilities and the gate
  • Dependency verification at boot
  • Cursor tokens
  • Health
  • mongo
  • Portable models
  • Upgrade notes
• Cache
  • Declaring
  • Configuring
  • What is cached, what invalidates it
  • Caching any coroutine
  • Disabled and missing
  • Memory to Redis
  • Failures
  • Lifecycle
• Examples repo
  • 1. Model layer
  • 2. Commands
  • 3. Use cases
  • 4. Background jobs
  • 5. Job dispatch from use cases
  • 6. Job callbacks
  • 7. Workflow: chain a use case + dispatch
  • 8. REST interface
  • 9. Bootstrap
  • Source files
• REST Testing
  • Unit-test a use case directly
  • HTTP-level testing
  • Golden harness
  • Integration tests
  • Snapshot testing

ETL

• ETL
  • Install
  • Minimal pipeline
  • File source with JSON payload + final CSV report
  • File aliases (FileLocator)
  • YAML config (Polars path)
  • Config values and secrets (FromConfig)
  • Agents (WithAgent)
  • Write modes
  • Running only selected stages
  • Spark runtime
  • Testing ETL steps
  • File aliases (FileLocator)
  • Loading config from cloud storage
  • Pluggable config resolvers
  • End-to-end example
  • API reference
• Agents in ETL steps (WithAgent)
  • A complete example
  • What map returns
  • How it runs
  • Versions
  • What is checked before anything is spent
  • Without from_yaml
• ETL Testing
  • Test a single step with Polars
  • Reusable seed datasets with ETLScenario
  • Spark integration tests
  • Compile-time stubs
• ETL Examples
  • What it covers
  • Quick start
  • Next steps

Streaming

• Bytewax Runtime
  • What it does
  • Public entrypoint
  • When to use it
  • Flow contract
  • Writing your own destination
  • Booting from YAML (resolvers=)
  • Runtime notes
• Delivery, Scaling, and Recovery
  • Delivery semantics
  • Scaling model
  • Recovery and snapshots
  • Runtime tuning
• Message lifecycle tracing
  • The trace id is the message’s
  • The spans of one message
  • Batches: the N+1 rule
  • Configuration
  • Known limits

AI Agents

• Agents Overview
  • Stability
  • Install
  • The shape of a deployment
  • An application that is only agents
  • When loom is not enough: the escape hatch
  • Where to go next
• Agent Artifact Reference (spec_version: 1)
  • Folder layout
  • A complete artifact
  • Top-level fields
  • output — the declared answer shape
  • on_output — a use case run once per completed run
  • conversation — loading the prior turns
  • capabilities — the seven kinds
  • policies — execution limits
  • The agent’s version — AgentPlan.fingerprint
  • Validating offline
  • The published JSON Schema
• Model Providers
  • The matrix
  • gateway is a protocol, not a vendor
  • Several roles at once
  • typesafe fills an output, it never writes text
  • Credentials never live in the artifact — or in the config
  • Vendor-specific settings
  • Pinning the structured-output mode
  • Asking for the answer whole, not as a stream
  • What does not happen
• The A2A Surface
  • Outbound — delegating to a remote agent
  • Inbound — publishing your agent
  • Methods
  • Event mapping
  • Security
• MCP Deployment
  • The shape: a sideways call, never a gateway
  • Configuring a server
  • Authentication
  • Reuse the agent’s connection from Python
  • Reach a server directly, with no agent in the middle
  • The rule: your own tools are a usecase grant
  • Operational notes
• Observability and Logfire
  • The logfire extra
  • Bootstrap
  • What the spans carry
  • Health

Reference

• Reference
  • Core API
  • ETL API
  • Streaming API
  • Repository API
  • REST API
  • AI API
  • Testing API