Skip to content

docs(readme): Phase 1 — align OSS README with runtime platform #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
betterdataco merged 2 commits into from
May 21, 2026
Merged

docs(readme): Phase 1 — align OSS README with runtime platform #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a3d5191
docs(readme): align OSS README with runtime platform framing
betterdataco May 21, 2026
ba0a978
docs(readme): complete Phase 1 runtime platform README
betterdataco May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 67 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,61 @@
# 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)
[![loopengine.io](https://img.shields.io/badge/docs-loopengine.io-blue)](https://loopengine.io)

## 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)
- 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.

## Why Loop Engine?
## 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.

AI systems make recommendations. Humans approve decisions. Workflows execute actions. But who governed what happened in between?
## Why Loop Engine?

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
↓
Channels (human surfaces)
↓
Loop Engine ← decision governance
Integrations (enterprise systems)
↓
Workflow / ERP / Infrastructure
Evidence + learning
```

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

```bash
Expand Down Expand Up @@ -94,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

Full docs at **[loopengine.io](https://loopengine.io)**
**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.

Runnable examples in [github.com/loopengine/loop-examples](https://github.com/loopengine/loop-examples):
**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).

- 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
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.

## Platform direction

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).
Loading