abstractgateway 0.2.4

AbstractGateway: deployable Run Gateway host for AbstractRuntime (commands + ledger).

AbstractGateway

AbstractGateway is a deployable Run Gateway host for AbstractRuntime runs:

• start durable runs
• accept a durable command inbox
• replay/stream a durable ledger (replay-first)
• enforce a security baseline (token + origin allowlist + limits)

This decouples the gateway service from any specific UI (AbstractFlow, AbstractCode, web/PWA thin clients).

Start here: docs/getting-started.md

AbstractFramework ecosystem

AbstractGateway is part of the AbstractFramework ecosystem:

• AbstractRuntime (required): durable run model + workflow registry + stores (pyproject.toml, src/abstractgateway/runner.py)
• AbstractCore / AbstractVoice / AbstractVision (optional via abstractgateway[multimodal] / [server]): LLM/tool execution, provider-level prompt-cache controls, and workflow-backed/direct generated image/voice/audio capabilities used by many bundles (src/abstractgateway/hosts/bundle_host.py)
• Higher-level UIs (optional): AbstractFlow (authoring/bundling), AbstractCode / AbstractObserver / thin clients (rendering + operations)

Related repos:

• AbstractFramework: https://github.com/lpalbou/AbstractFramework
• AbstractCore: https://github.com/lpalbou/abstractcore
• AbstractRuntime: https://github.com/lpalbou/abstractruntime

Quickstart (HTTP server, bundle mode)

pip install "abstractgateway[http]"

export ABSTRACTGATEWAY_FLOWS_DIR="/path/to/bundles"   # *.flow dir (or a single .flow file)
export ABSTRACTGATEWAY_DATA_DIR="$PWD/runtime/gateway"

# Required by default: the server refuses to start without a token.
export ABSTRACTGATEWAY_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
# Browser-origin allowlist (glob patterns). Default allows localhost; customize when exposing remotely.
export ABSTRACTGATEWAY_ALLOWED_ORIGINS="http://localhost:*,http://127.0.0.1:*"

abstractgateway serve --host 127.0.0.1 --port 8080

OpenAPI docs (Swagger UI): http://127.0.0.1:8080/docs

Smoke checks:

curl -sS "http://127.0.0.1:8080/api/health"

curl -sS -H "Authorization: Bearer $ABSTRACTGATEWAY_AUTH_TOKEN" \
  "http://127.0.0.1:8080/api/gateway/bundles"

Docker server

Release images are published to GHCR. The default image is the light, portable server image:

docker pull ghcr.io/lpalbou/abstractgateway-server:0.2.4

NVIDIA hosts can try the experimental full GPU image when local vLLM/HuggingFace/Diffusers engines are wanted. This image is published best-effort until it has a real CUDA build and smoke gate:

docker pull ghcr.io/lpalbou/abstractgateway-server-nvidia:0.2.4

The image installs abstractgateway[server,memory]: HTTP server, AbstractRuntime[multimodal], AbstractCore remote/commercial provider support, OpenAI-compatible text providers, workflow-backed and direct image generation through Runtime/Core/AbstractVision, direct Gateway voice/audio endpoints through AbstractVoice, provider/session prompt-cache helpers, media/tool helpers, token counting, compression, AbstractMemory/LanceDB KG support, AbstractAgent, and AbstractFlow compatibility.

export ABSTRACTGATEWAY_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

docker run --rm --name abstractgateway-server \
  -p 127.0.0.1:8080:8080 \
  -e ABSTRACTGATEWAY_AUTH_TOKEN="$ABSTRACTGATEWAY_AUTH_TOKEN" \
  -e ABSTRACTGATEWAY_PROVIDER="openai-compatible" \
  -e ABSTRACTGATEWAY_MODEL="your-model" \
  -e OPENAI_COMPATIBLE_BASE_URL="http://host.docker.internal:1234/v1" \
  -v "$PWD/runtime/gateway:/data/gateway" \
  -v "$PWD/flows/bundles:/data/flows:ro" \
  ghcr.io/lpalbou/abstractgateway-server:0.2.4

On Apple Silicon, keep Metal/MLX inference native on macOS and run the lightweight Gateway container as the transport/control plane. Point OPENAI_COMPATIBLE_BASE_URL at a host-native OpenAI-compatible endpoint such as Docker Model Runner (http://model-runner.docker.internal/engines/v1), LM Studio (http://host.docker.internal:1234/v1), Ollama (http://host.docker.internal:11434/v1), or mlx_lm.server on a host port. For native non-Docker installs with local engines, use pip install "abstractgateway[apple]" or pip install "abstractgateway[all-apple]" on Apple Silicon, and pip install "abstractgateway[gpu]" or pip install "abstractgateway[all-gpu]" on GPU workstations.

Compose and deployment details: docs/deployment.md.

0.2.4 capability scope

Direct Gateway APIs in this release:

• POST /api/gateway/runs/{run_id}/voice/tts
• POST /api/gateway/runs/{run_id}/audio/transcribe
• POST /api/gateway/runs/{run_id}/images/generate
• GET /api/gateway/voice/voices
• GET /api/gateway/audio/speech/models
• GET /api/gateway/vision/provider_models
• /api/gateway/prompt_cache/* provider/model operator controls
• /api/gateway/sessions/{session_id}/prompt_cache/* session lifecycle controls
• /api/gateway/kg/query with configurable lancedb or in-memory AbstractMemory stores, plus sqlite when the installed AbstractMemory build exposes SQLiteTripleStore
• /api/gateway/discovery/capabilities package, plugin, and thin-client contract discovery

Workflow/Core-backed capabilities:

• Generated images are available to Runtime/Core workflows through AbstractVision when installed and configured, and the direct Gateway image route uses the same Runtime/Core image-generation contract.
• Prompt-cache support depends on the active provider/model. Session lifecycle routes provide Gateway-owned naming and orchestration, not a provider- independent local KV cache.

Client contract (replay-first)

• Clients start runs: POST /api/gateway/runs/start
• Clients can schedule runs (bundle mode): POST /api/gateway/runs/schedule
• Clients act by submitting durable commands: POST /api/gateway/commands
  • supported types: pause|resume|cancel|emit_event|update_schedule|compact_memory
• Clients render by replaying/streaming the durable ledger:
  • replay: GET /api/gateway/runs/{run_id}/ledger?after=...
  • stream (SSE): GET /api/gateway/runs/{run_id}/ledger/stream?after=...

See docs/api.md for curl examples and the live OpenAPI spec (/openapi.json).

Install

Base (runner + stores + CLI)

Requires Python >=3.10 (see pyproject.toml).

pip install abstractgateway

HTTP API/SSE server (FastAPI + Uvicorn)

pip install "abstractgateway[http]"

Optional extras

• abstractgateway[visualflow]: run VisualFlow JSON from a directory of *.json files (requires abstractflow)
• abstractgateway[server]: container/server profile with AbstractRuntime multimodal support, AbstractCore remote providers, OpenAI-compatible text providers, workflow-backed/direct AbstractVision image generation, direct Gateway voice/audio/image endpoints, provider/session prompt-cache helpers, media/tool helpers, tokens, and compression
• abstractgateway[memory]: AbstractMemory TripleStore KG support with LanceDB as the default durable vector-capable backend; in-memory is a runtime config choice, and SQLite is supported when the installed AbstractMemory build exposes SQLiteTripleStore
• abstractgateway[apple] / abstractgateway[all-apple]: full native macOS Python profiles with Apple-local engines and all non-NVIDIA framework capabilities
• abstractgateway[gpu] / abstractgateway[all-gpu]: full native GPU Python profiles with local GPU engines and all relevant framework capabilities
• abstractgateway[server-nvidia]: experimental full NVIDIA profile with vLLM/HuggingFace, local Diffusers image generation, and local voice engines; used by the best-effort abstractgateway-server-nvidia image
• abstractgateway[telegram]: Telegram bridge dependencies
• abstractgateway[voice]: explicit voice/audio profile for TTS/STT via AbstractVoice and AbstractCore's voice/audio plugin extras
• abstractgateway[vision]: explicit generative vision profile via AbstractCore's AbstractVision plugin
• abstractgateway[multimodal]: Runtime/Core multimodal profile without the HTTP server deps
• abstractgateway[all]: batteries-included install (HTTP + tools + voice/audio + vision + media + visualflow)
• abstractgateway[docs]: MkDocs site tooling
• abstractgateway[dev]: local test/dev deps

Bundle-dependent dependencies (only if your workflows need them)

• LLM/tool nodes in bundle mode require AbstractRuntime’s AbstractCore integration.
  • Install abstractgateway[multimodal], abstractgateway[server], or abstractgateway[all].

Visual Agent nodes require abstractagent (also included by abstractgateway[server] and abstractgateway[all]):

pip install abstractagent

KG memory nodes use Gateway's memory resolver:

pip install "abstractgateway[memory]"
export ABSTRACTGATEWAY_MEMORY_STORE_BACKEND=lancedb  # lancedb|memory; sqlite if available

Use memory for process-local dev/test stores. sqlite is supported when the installed AbstractMemory build exposes SQLiteTripleStore.

Gateway has a first-class config helper:

abstractgateway-config status
abstractgateway config init --env-file .env

For details on ABSTRACTGATEWAY_PROVIDER/MODEL, store backends, and workflow sources, see docs/configuration.md.

Creating a .flow bundle (authoring)

Use AbstractFlow to pack a bundle:

abstractflow bundle pack /path/to/root.json --out /path/to/bundles/my.flow --flows-dir /path/to/flows

See docs/getting-started.md for running, split API/runner, and file→SQLite migration.

Docs

Published docs site: https://www.lpalbou.info/AbstractGateway/

Project docs

• Changelog: CHANGELOG.md (compat: CHANGELOD.md)
• Contributing: CONTRIBUTING.md
• Security policy (vulnerability reporting): SECURITY.md
• Acknowledgments: ACKNOWLEDGMENTS.md (compat: ACKNOWLEDMENTS.md)

Package docs

• Docs index: docs/README.md
• Getting started: docs/getting-started.md
• FAQ: docs/faq.md
• Architecture: docs/architecture.md
• Configuration: docs/configuration.md
• Deployment: docs/deployment.md
• API overview: docs/api.md
• Security: docs/security.md
• Operator tooling (optional): docs/maintenance.md