From a3d519189864c7fa82b47f7440d9eb8c069740a3 Mon Sep 17 00:00:00 2001 From: Todd Palmer Date: Thu, 21 May 2026 08:52:33 -0700 Subject: [PATCH 1/2] docs(readme): align OSS README with runtime platform framing Phase 1: canonical primary/supporting copy, runtime model diagram, loopengine.io as docs authority. --- README.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index c8aee52..9454561 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Loop Engine -> Open runtime for governed, observable enterprise loops. +> An open governed operational runtime platform for AI-assisted enterprise systems. [![npm](https://img.shields.io/npm/v/@loop-engine/sdk.svg?label=@loop-engine/sdk)](https://www.npmjs.com/package/@loop-engine/sdk) [![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) @@ -8,7 +8,9 @@ ## What is Loop Engine? -Loop Engine is an open runtime for governing decisions made by AI agents, humans, and automations working together. +Loop Engine is an open governed operational runtime platform for AI-assisted enterprise systems. + +Loop Engine connects AI providers, communication channels, and enterprise systems through decision loops. Every transition through a loop: - Names the actor responsible (human, automation, or AI agent) @@ -20,18 +22,22 @@ This creates a decision record produced at runtime, not reconstructed afterward. ## Why Loop Engine? -AI systems make recommendations. Humans approve decisions. Workflows execute actions. But who governed what happened in between? - -Loop Engine sits between AI reasoning and operational execution. It enforces who can do what, under what conditions, with what evidence. +AI systems make recommendations. Humans approve on channels they already use. Enterprise systems execute side effects. Loop Engine governs what happens between them — who may transition, under which guards, with what evidence. ```text -AI Agent +Providers (intelligence) + ↓ +Decision loops + guards ↓ -Loop Engine ← decision governance +Channels (human surfaces) ↓ -Workflow / ERP / Infrastructure +Integrations (enterprise systems) + ↓ +Evidence + learning ``` +Loop Engine is not a workflow engine, Slack bot, or generic integration platform. It is governance substrate for AI-assisted operations — local-first, developer-operable, Apache-2.0. + ## Quick Start ```bash @@ -119,7 +125,7 @@ Core primitives are bundled in `@loop-engine/sdk`. Internal monorepo-only packag ## Documentation -Full docs at **[loopengine.io](https://loopengine.io)** +Canonical documentation lives at **[loopengine.io](https://loopengine.io)** (runtime, taxonomy, examples, self-host). - [Quick Start](https://loopengine.io/docs/getting-started/quick-start) - [Core Concepts](https://loopengine.io/docs/core-concepts) From ba0a978d7d1c20fe2942b03eaf0bd1ee35996106 Mon Sep 17 00:00:00 2001 From: Todd Palmer Date: Thu, 21 May 2026 08:57:07 -0700 Subject: [PATCH 2/2] docs(readme): complete Phase 1 runtime platform README Runtime-today table, hosted Cloud boundary, platform direction without overpromising; packages as implementation layer; loopengine.io as canonical docs. --- README.md | 98 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 9454561..942870e 100644 --- a/README.md +++ b/README.md @@ -13,13 +13,29 @@ Loop Engine is an open governed operational runtime platform for AI-assisted ent Loop Engine connects AI providers, communication channels, and enterprise systems through decision loops. Every transition through a loop: + - Names the actor responsible (human, automation, or AI agent) - Evaluates guard policies before allowing the action -- Attaches structured evidence - what information the actor used +- Attaches structured evidence — what information the actor used - Emits an immutable event with full attribution This creates a decision record produced at runtime, not reconstructed afterward. +## What exists today + +Loop Engine is an **OSS operational substrate** you run in your environment — local-first, developer-operable, governance-native. + +| Capability | Status | +| --- | --- | +| Decision loop runtime (`@loop-engine/sdk`, `@loop-engine/runtime`) | Shipped | +| Guards, actors, events, signals (core primitives) | Shipped | +| Provider adapters (Anthropic, OpenAI, Gemini, Grok, Perplexity tool path) | Shipped | +| Persistence adapters (memory, Postgres, Kafka) | Shipped | +| Routing / human surfaces (OpenClaw, PagerDuty, Vercel AI SDK patterns) | Shipped | +| Observability timelines and replay | Shipped | + +Install one SDK entrypoint, add adapters for your stack, define loops in YAML or TypeScript. Full taxonomy and guides live on **[loopengine.io](https://loopengine.io)** — the canonical documentation surface for this runtime. + ## Why Loop Engine? AI systems make recommendations. Humans approve on channels they already use. Enterprise systems execute side effects. Loop Engine governs what happens between them — who may transition, under which guards, with what evidence. @@ -36,7 +52,9 @@ Integrations (enterprise systems) Evidence + learning ``` -Loop Engine is not a workflow engine, Slack bot, or generic integration platform. It is governance substrate for AI-assisted operations — local-first, developer-operable, Apache-2.0. +Loop Engine is **not** a workflow engine, Slack bot, or generic integration platform. It is governance substrate for AI-assisted operations. + +**Workflows define the path. Loops govern the transitions.** Durable orchestrators (Temporal, n8n, application code) may execute approved work; Loop Engine decides whether state may change and records evidence first. ## Quick Start @@ -100,63 +118,55 @@ await engine.transition({ }) ``` -## Packages - -| Package | Description | -|---|---| -| [`@loop-engine/sdk`](packages/sdk) | Main SDK - start here | -| [`@loop-engine/runtime`](packages/runtime) | Loop lifecycle and transitions | -| [`@loop-engine/observability`](packages/observability) | Timeline and replay | -| [`@loop-engine/adapter-memory`](packages/adapter-memory) | In-memory storage | -| [`@loop-engine/adapter-postgres`](packages/adapters/postgres) | PostgreSQL storage | -| [`@loop-engine/adapter-kafka`](packages/adapters/kafka) | Kafka event streaming | -| [`@loop-engine/adapter-anthropic`](packages/adapter-anthropic) | Claude AI actor | -| [`@loop-engine/adapter-openai`](packages/adapter-openai) | OpenAI AI actor | -| [`@loop-engine/adapter-grok`](packages/adapter-grok) | Grok (xAI) AI actor | -| [`@loop-engine/adapter-gemini`](packages/adapter-gemini) | Gemini AI actor | -| [`@loop-engine/adapter-perplexity`](packages/adapter-perplexity) | Perplexity Sonar (`ToolAdapter`, citations) | -| [`@loop-engine/adapter-openclaw`](packages/adapter-openclaw) | OpenClaw integration | -| [`@loop-engine/adapter-commerce-gateway`](packages/adapter-commerce-gateway) | Commerce Gateway | -| [`@loop-engine/adapter-pagerduty`](packages/adapter-pagerduty) | PagerDuty incidents | -| [`@loop-engine/adapter-vercel-ai`](packages/adapter-vercel-ai) | Vercel AI SDK | - -Core primitives are bundled in `@loop-engine/sdk`. Internal monorepo-only packages for contributors are: -`core`, `dsl`, `guards`, `actors`, `events`, and `signals`. +## npm packages (implementation layer) + +`@loop-engine/*` packages implement the runtime — start with [`@loop-engine/sdk`](packages/sdk). Adapters are optional by surface: + +| Layer | Packages | +| --- | --- | +| Runtime core | `sdk`, `runtime`, `guards`, `actors`, `events`, `signals` | +| Providers | `adapter-anthropic`, `adapter-openai`, `adapter-gemini`, `adapter-grok`, `adapter-perplexity` | +| Channels / routing | `adapter-openclaw`, `adapter-vercel-ai`, `adapter-pagerduty` | +| Integrations | `adapter-postgres`, `adapter-kafka`, `adapter-http`, `adapter-commerce-gateway`, `adapter-memory` | + +Contributor-only monorepo packages: `core`, `dsl`, and related internals bundled through `sdk` for app developers. ## Documentation -Canonical documentation lives at **[loopengine.io](https://loopengine.io)** (runtime, taxonomy, examples, self-host). +**Canonical documentation:** **[loopengine.io/docs](https://loopengine.io/docs)** — runtime model, taxonomy, examples, and self-host paths. This repository README is a GitHub entrypoint; do not treat the package table above as the product story. - [Quick Start](https://loopengine.io/docs/getting-started/quick-start) -- [Core Concepts](https://loopengine.io/docs/core-concepts) -- [Examples](https://loopengine.io/docs/examples) +- [Architecture](https://loopengine.io/docs/getting-started/architecture) - [Integrations](https://loopengine.io/docs/integrations) -- [Perplexity Sonar & Computer (OSS)](docs/integrations-perplexity.md) +- [Examples](https://loopengine.io/docs/examples) -## Examples +## Loop Engine Cloud (hosted boundary) + +**Loop Engine** (this repo) is the open runtime you self-host. + +**Loop Engine Cloud** is Better Data’s hosted governance control plane — multi-tenant runtime, connectors, and API keys at [loops.betterdata.co](https://loops.betterdata.co). Contract and operational details: [loopengine.io/docs/integrations/loop-engine-cloud-api](https://loopengine.io/docs/integrations/loop-engine-cloud-api). + +We do not claim feature parity between every OSS adapter and Cloud connectors in this README; see hosted docs for what is available in your tenant. -Runnable examples in [github.com/loopengine/loop-examples](https://github.com/loopengine/loop-examples): +## Platform direction -- Expense Approval - human-only approval gate -- AI Replenishment - Claude + OpenAI as governed actors -- Demand Signal - rule-based loop triggering -- Postgres Persistence - production storage adapter -- Event Streaming - Kafka event pipeline +Roadmap themes (not delivery commitments): richer runtime taxonomy docs on loopengine.io, expanded channel adapters, and deeper hosted connector coverage. We avoid promising undelivered surfaces (e.g. multi-service compose stacks or studio products) in OSS copy — direction is shared on [loopengine.io/changelog](https://loopengine.io/docs/changelog) and GitHub discussions. + +## Examples + +Reference walkthroughs on [loopengine.io/docs/examples](https://loopengine.io/docs/examples). The [loop-examples](https://github.com/loopengine/loop-examples) repository is being brought up to match current SDK APIs — verify runnable status before citing copy-paste flows. ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md). Open issues and RFCs at [github.com/loopengine/loop-engine/discussions](https://github.com/loopengine/loop-engine/discussions). +See [CONTRIBUTING.md](CONTRIBUTING.md). RFCs and discussions: [github.com/loopengine/loop-engine/discussions](https://github.com/loopengine/loop-engine/discussions). -## Provenance and package trust +## Provenance - **Canonical repository:** https://github.com/loopengine/loop-engine -- **Maintainer organization:** Better Data, Inc. (https://betterdata.co) -- **Package family:** `@loop-engine/*` packages in `packages/` -- **Issue tracker:** https://github.com/loopengine/loop-engine/issues -- **Documentation site:** https://loopengine.io +- **Maintainer:** Better Data, Inc. — https://betterdata.co +- **Documentation:** https://loopengine.io +- **Issues:** https://github.com/loopengine/loop-engine/issues ## License -Apache-2.0 - see [LICENSE](LICENSE) for details. - -Created and maintained by [Better Data](https://betterdata.co). +Apache-2.0 — see [LICENSE](LICENSE).