An open-source ecosystem for building durable, observable, multimodal AI systems.
Two things share the name:
- The ecosystem: composable packages (Core, Runtime, Agent, Gateway, Flow, Observer, apps, modality plugins).
- This repo / meta-package:
abstractframeworkis a pinned install profile + cross-package docs.
If you're looking for the main SDK, that's AbstractCore. If you need durable orchestration, that's AbstractGateway.
- AbstractCore — when you want direct LLM/tool/media integration with a clean, provider-agnostic API (Python SDK or OpenAI-compatible
/v1). - AbstractGateway — when you need durability, orchestration, scheduling, or language-agnostic access via HTTP/SSE routes.
Most teams start with Core (SDK or /v1), then introduce Gateway when workflows become long-running, scheduled, or shared across clients. See Getting Started.
No.
| Goal | Install |
|---|---|
| A running gateway + web console, no Python setup | the installer (a Mac package, or one line) in Install |
| Smallest useful (LLM SDK only) | pip install abstractcore (every remote provider); abstractcore[apple] or abstractcore[gpu] add the local engines |
| Gateway-first deployment | pip install abstractgateway |
| Everything at compatible versions | pip install abstractframework |
| A browser app | the gateway console's Apps page (served at /apps/<app>/ on the gateway), or on its own: npx @abstractframework/<flow|code|observer|continuum|entity> --gateway-url <url> |
| A terminal client | cargo install abstractcode, cargo install abstractgateway-console or cargo install abstractcore-console |
| A container deployment | ghcr.io/lpalbou/abstractgateway:0.14.0 |
See Install AbstractFramework for the Light / Apple / GPU chooser. Light is remote-first, not reduced-functionality: multimodal and embeddings still work through remote or local endpoint providers.
Yes. The core execution stack works fully offline with local model servers (Ollama, LM Studio, vLLM, llama.cpp, LocalAI). You need internet only to download models or use cloud APIs.
Multimodal plugins also work offline:
- AbstractVoice: Piper TTS (ONNX) + faster-whisper STT — prefetch once, run offline.
- AbstractVision: local Diffusers models or GGUF via stable-diffusion.cpp.
- AbstractMusic: local ACE-Step inference.
AbstractAgent ships three patterns, all built on the durable Runtime kernel:
| Pattern | How it works |
|---|---|
| ReAct | Tool-first reasoning: observe → think → choose tool → execute → reflect |
| CodeAct | Code execution: generate Python, run it, observe output |
| MemAct | Memory-enhanced: reads/writes a knowledge graph during the loop |
Agents can run standalone or as nodes inside an AbstractFlow workflow.
Direct SDKs are fine when you only use one provider and don't need durable orchestration.
AbstractCore adds value when you need: provider portability (local ↔ cloud), consistent tool/structured-output behavior across backends, media policies, modality plugins, or a configuration layer that doesn't leak into app code.
Most agent libraries are in-process orchestration. AbstractFramework is a durable orchestration stack.
Where AbstractFramework is stronger: durability and pause/resume as primitives, replay-first observability, portable .flow bundles that run across clients.
Where others are stronger: large connector/RAG ecosystems, minimal boilerplate for simple use cases, broader community examples.
AbstractGateway is architecturally closer to these, but specialized for LLM/tool loops: tool approval waits, AI-oriented artifacts, and replay-first thin-client UIs over HTTP/SSE.
Yes. Use AbstractFramework for orchestration and durability; integrate other libraries as tools or subflows:
- Use LlamaIndex retrievers as tools within an AbstractAgent
- Wrap LangChain chains as tool executors
- Let AbstractRuntime handle durability while external libraries handle specific capabilities
A .flow file is the portable distribution unit for workflows. It packages:
- A VisualFlow workflow graph
- Metadata (entry points, interfaces)
- Optional subflows and assets
Deploy a bundle to a gateway and any gateway-backed client can discover and run it.
- Run a gateway (for durability + discovery).
- Open the Flow Editor from the gateway console's Apps page (or
npx @abstractframework/flow --gateway-url <url>). - Build a workflow: LLM steps, tool steps, agent nodes, branching, loops, subflows.
- Export to
.flow. - Copy into
ABSTRACTGATEWAY_FLOWS_DIRto deploy.
To make it reusable across clients, implement an interface contract (for example abstractcode.agent.v1).
See Getting Started → "Author orchestration with AbstractFlow".
- Monitoring: use AbstractObserver — replay ledger, stream live execution, inspect errors, control runs.
- Recurring work: create an automation — from the Observer (Launch → Automate), from an
Assistant conversation (Schedule this conversation…) or through
POST /api/gateway/automations. The gateway runs it, it survives restarts, and each run is readable as a conversation turn.
See Automations and Getting Started → "Gateway-first" section.
An automation is one durable run on the runtime (the controller). Each time its trigger fires, it starts one occurrence, a run of your workflow that clients show as a question/answer turn:
- Independent context starts every occurrence fresh; growing context makes the occurrences successive turns of one conversation, with a bounded history (the most recent 50 000 tokens of whole turns).
- Automations are quiet by default: you are notified when the workflow's output carries
notify, when a run fails after its last retry, or when a run waits for you. - Creating an automation is the consent for the framework tools its workflow uses; choose Ask each time to approve every tool batch. MCP tools always ask.
- Triggers are fixed UTC intervals (
5m,8h,7d), new mail in your own mailbox (email.received@1) and Run now; there is no cron, time of day, webhook or file trigger.
The full guide, with two worked examples and troubleshooting, is Automations.
Only with an account you connect yourself, and only as far as you allow. Each gateway user connects
their own mailbox on their account page in the web console (Email on their row of
Accounts) or the terminal console
(@ on the Accounts screen); AbstractCore on its own uses abstractcore email connect. Credentials are encrypted at
rest and every connection verifies TLS. The mailbox is read-only: nothing is marked, moved or
deleted. Every send passes your recipient rules (an allowlist or a denylist of addresses and
domains; a new account allows only your own email address) and your send limits (100 per hour, 1000 per
day by default), and a send to anyone but you (or the recipients an automation lists) waits for
your approval. Agents get the email tools only when you switch Agent email tools on (off by
default); administrators never read users' mail. An email-triggered automation treats
mail as untrusted data and never follows its links unless you allow those tools, and mail the
framework sends automatically through your account never triggers an automation. See
Email integration and Email automations.
Yes. The gateway's web console and the five browser apps work on phones, tablets and any window
size. Let the phone reach the gateway (abstractgateway network set lan, then
abstractgateway network restart --token <admin token>), then open the console on
the phone at the gateway's address; every installed app opens from its Apps page at
/apps/<app>/ on that same address. With Tailscale, tailscale serve --bg http://127.0.0.1:<port>
on the gateway's computer gives an https address (https://<host>.<tailnet>.ts.net/) that also
works away from home and lets voice and camera work in the browser. See
Phones and tablets.
The gateway's default agent workflow for the client's interface, unless you pick another in the
client. AbstractCode uses the shipped basic-agent until an admin chooses another
(agents.default_workflow.abstractcode.agent.v1); the Assistant runs its built-in orchestrator
unless the gateway names one. Clients that follow the gateway default pick up a change at the next
turn. See Agent sessions.
In a folder on the gateway's computer: the conversation's own private folder under the gateway's
data folder, or a workspace the client names (such as the folder you started the AbstractCode
terminal client from) when the gateway's workspace policy reaches it. A file written without a full
path lands there, not in the shared workspace. Beyond that folder the agent may use the Shared
workspace and the workspaces the admin's posture allows, each Read-only or Read & write; it is
told their paths and modes. AbstractCode's Files tab and /files show its absolute path and
preview its files. Credential folders (~/.ssh,
~/.aws, ~/.gnupg, ~/.config/gcloud, ~/.kube, ~/Library/Keychains), the framework's own
settings folders and the gateway's data folder are denied to every run's file tools and never
shown by the workspace browser. Shell commands a run may execute are not confined by that list,
so keep shell tools behind approval. See
Agent sessions.
With live replies on (the gateway's agents.streaming_default, or Stream replies in the
client), the text and reasoning of every model call in the run stream, sub-agents included.
Structured-output calls, a gateway that calls a remote AbstractCore server, providers that cannot
stream or report usage while streaming, and entity chat do not; the client says why in one line,
and the finished answer is the same either way. See
Agent sessions.
Yes. Ejecting a model (console Resources, abstractgateway models unload) frees it from every
holder in the gateway process, for MLX, llama.cpp GGUF, transformers and embedding models, caches
included. Switching the default model ejects the previous one before the new one loads when nothing
else uses it. The console's accelerator meter shows the memory the gateway process holds and how
it was measured. See Architecture and
Troubleshooting.
Every app renders the same framework identity (name, website, author, licence, links, contact)
from one descriptor kept in this repository, identity/abstractframework.json, plus the
versions the connected gateway reports at GET /api/gateway/about. See
Architecture.
AbstractCore supports modalities via capability plugins (installed separately, discovered via entry points):
| Plugin | Capability |
|---|---|
abstractvoice |
llm.voice (TTS) / llm.audio (STT) |
abstractvision |
llm.vision (image generation) |
abstractmusic |
llm.music (text-to-music) |
Plugins are configured on the machine that actually executes (local app host or gateway host). Don't install a plugin; Core stays lightweight.
- Gateway: its data folder is the durability root (runs, ledger, artifacts, schedules, conversation workspaces, the seeded skill shelf, saved settings). By default it is
~/Library/Application Support/AbstractGateway(macOS),~/.local/share/abstractgateway(Linux) or%LOCALAPPDATA%\AbstractGateway(Windows);serve --data-dirchooses another, andabstractgateway-config statusprints the one in use. - Core config:
~/.abstractcore/config/(persisted byabstractcore --config). - Local apps:
~/.abstractcode/(terminal client preferences),~/.abstractassistant/(Assistant preferences, sign-in and chat snapshots), etc.
If you care about auditability and long-lived workflows, back up the gateway data directory.
AbstractFramework-Installer.pkg is not signed with an Apple Developer ID, so macOS blocks the
first double-click. Open System Settings > Privacy & Security and click Open Anyway next to
the installer's name, once per download. The one-line install in Terminal does not show this
step. See Install on a Mac.
Yes, when you choose it. The gateway listens on this computer only until you change its Network
setting (abstractgateway network set lan, the console, or the menu-bar icon). See
Network setting.
The commands live in ~/.local/bin (%USERPROFILE%\.local\bin on Windows). The script runs
uv tool update-shell once to add that directory to your PATH, which applies to new
terminals. Open a new terminal, or call ~/.local/bin/abstractgateway directly. Pass
--no-modify-path if you manage PATH yourself.
8080 by default. When something else already listens there (for example llama-server or
mlx_lm.server, which also default to 8080), the script picks the next free port, remembers it
for later runs, and prints the console URL. Choose one with --port N (-Port N).
A gateway of this install that you started yourself (for example with abstractgateway serve --data-dir <data dir>) is not "something else": the installer recognizes it (it serves the same
data directory, from its serve record <data dir>/run/gateway-serve.json or its --data-dir), keeps
its port and replaces it with its own start, so one gateway serves your data. The replacement binds
as the gateway's Network setting says (abstractgateway network status), so a gateway you started
with --host 0.0.0.0 comes back on the Network setting's address. With --no-start
(-NoStart) it leaves that gateway running and says a restart is due.
Not for the default install: uv, Python, the gateway and Node (nodejs-wheel) install in your
user account. Only optional vendor installers may: Ollama on Linux uses sudo (it installs a system
service), Ollama on macOS may ask to link /usr/local/bin/ollama, and LM Studio on Linux may ask
to install libatomic1. The script tells you before running them.
No. The default install uses prebuilt wheels only. If macOS shows an "install the command line
developer tools" prompt, cancel it and re-run the one-liner. llama.cpp GGUF models come from upstream's prebuilt wheel on Apple
Silicon, Linux and Windows x64 (llama.cpp GGUF models). You
need a compiler only for --full, which adds stable-diffusion.cpp and (macOS, Linux) echo cancellation, and
llama.cpp on machines without a prebuilt wheel (Compiled extras).
On Linux with the gpu profile, vLLM also needs a C compiler (build-essential) the first time it
starts a model (GPU on Linux (NVIDIA)).
Yes, with the light profile (remote and endpoint engines). [apple] needs macOS 14 or newer:
MLX publishes no wheels for macOS 13, so the installer picks the light profile on 13 (it prints
"the Apple Silicon engines (MLX) need macOS 14 or later") and refuses --profile apple, and
pip install "abstractframework[apple]" on macOS 13 fails to resolve. After updating macOS to 14 or
later, run the installer again to add the local engines (an install made by 0.10.0 or older keeps
light on a re-run: add --profile apple)
(Requirements per profile).
Yes, on Linux and Windows x64: when nvidia-smi works, the installer picks the gpu profile
(--profile gpu / -Profile gpu forces it). On Linux it installs llama.cpp's CUDA build matching
PyTorch's CUDA and checks that PyTorch, llama.cpp and Whisper use the GPU. PyPI's PyTorch for Linux is
a CUDA 13 build and needs NVIDIA driver 580 or newer; with an older driver the engines run on the
processor. Install and per-capability timings measured on a Quadro RTX 5000 (16 GB, driver 595,
CUDA 13) with Ubuntu 26.04 are in GPU on Linux (NVIDIA). On Windows it installs PyTorch's CUDA build and
llama.cpp's prebuilt CUDA build, chosen from your driver version; this path is implemented but not
yet validated on real NVIDIA hardware. Each installer prints what runs where (PyTorch:, GGUF:
and Whisper lines) and falls back to the CPU for any part that does not work. See
GPU on Linux (NVIDIA) and
GPU on Windows (NVIDIA).
Pasting the one-liner works under the default Restricted policy because
powershell -ExecutionPolicy ByPass -c "irm … | iex" runs a command, not a script file, and the
bypass applies to that process only. If your organization sets the policy through Group Policy
(Get-ExecutionPolicy -List shows MachinePolicy or UserPolicy), a saved install.ps1 will not
run; use the one-liner or ask your administrator. The installer reports this during preflight.
The one-time link is valid for 10 minutes and works only from the same machine. Mint a new one with
abstractgateway claim --open (or abstractgateway-config claim-url). The admin token also stays
in <data dir>/auth/bootstrap-admin-token; the install summary prints that path.
From another device, sign in with your gateway user name and token. The sign-in page also offers Forgot your token? Email me a sign-in code (unless an administrator switched Sign-in by email off): an 8-digit code sent to your email address, valid once for 10 minutes. The code reaches you only when your account has an email address and a connected mailbox (Email on your row of the console's Accounts page). See Email integration.
When start at login is on, abstractgateway service status shows it,
abstractgateway service uninstall stops the gateway and removes the login entry (your data is
kept), and abstractgateway service install --port 8080 registers and starts it again. When it is
off (you answered no, the install ran without a terminal, or --no-service), the install summary
prints the stop and start commands and re-running the installer starts it again; turn start at
login on with the Start at login switch in either console or abstractgateway service enable.
Open the gateway console's Providers page (local engines: detect, install with the exact command
shown first, start, stop) and Models page (models that fit this machine, download, delete). From a terminal:
abstractgateway engines status|install and abstractgateway models catalog|download|delete.
Engine installs from the console run on the gateway host and are enabled by default only when the
gateway listens on loopback.
Add --print (Windows: -Print or -WhatIf). It runs the read-only checks and prints every
command without changing anything.
Run the install line again: it installs the latest AbstractFramework release, keeps your
settings, options and data, restarts the gateway when anything changed, and lists what changed.
On macOS and Linux, Update in the web console, the terminal console or the menu-bar icon runs
the same installer with --no-start: the running gateway keeps serving, and the console or icon
then offers the restart. An upgrade never installs less because of the network: a download that
fails, or a release not yet on every mirror, makes the installer run the same full install again
for about 10 minutes, then stop with the cause and the command to run again, the previous version
still installed and working. Coming from 0.6.1 or earlier, re-run the line once (the Update button of
gateway 0.7.1 cannot upgrade an installer install). --pin latest (-Pin latest) installs the
newest gateway instead. See Upgrade.
Re-run the script with --uninstall (-Uninstall). Add --purge (-Purge) to delete the gateway
data as well. See Remove AbstractFramework.
Symptoms, checks and fixes (provider calls failing, a browser app that cannot connect, missing voice models, install errors) are in Troubleshooting.