abstractgateway 0.1.0__tar.gz

abstractgateway-0.1.0/.gitignore

@@ -0,0 +1,178 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyc
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Node.js / Frontend
+node_modules/
+web/frontend/node_modules/
+web/frontend/dist/
+web/frontend/.vite/
+*.local
+
+# Package manager locks (optional - uncomment if you want to ignore)
+# package-lock.json
+# yarn.lock
+# pnpm-lock.yaml
+
+# TypeScript
+*.tsbuildinfo
+
+# ESLint
+.eslintcache
+
+# Vite
+*.local
+
+# SQLite databases (for flow storage)
+*.db
+*.sqlite
+*.sqlite3
+flows.db
+
+# Monaco Editor cache
+.monaco/
+
+
+web/runtime/

abstractgateway-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: abstractgateway
+Version: 0.1.0
+Summary: AbstractGateway: deployable Run Gateway host for AbstractRuntime (commands + ledger).
+Project-URL: GitHub, https://github.com/lpalbou/abstractgateway
+Author: Laurent-Philippe Albou
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: abstractruntime>=0.4.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: visualflow
+Requires-Dist: abstractflow>=0.3.0; extra == 'visualflow'
+Description-Content-Type: text/markdown
+
+# AbstractGateway
+
+AbstractGateway is the **deployable Run Gateway host** for AbstractRuntime runs:
+- durable command inbox
+- ledger replay/stream
+- security baseline (token + origin + limits)
+
+This decouples the gateway service from any specific UI (AbstractFlow, AbstractCode, web/PWA thin clients).
+
+## What it does (contract)
+- Clients **act** by submitting durable commands: `start`, `resume`, `pause`, `cancel`, `emit_event`
+- Clients **render** by replaying/streaming the durable ledger (cursor-based, replay-first)
+
+Endpoints:
+- `POST /api/gateway/runs/start`
+- `GET /api/gateway/runs/{run_id}`
+- `GET /api/gateway/runs/{run_id}/ledger`
+- `GET /api/gateway/runs/{run_id}/ledger/stream` (SSE)
+- `POST /api/gateway/commands`
+
+## Install
+
+### Default (bundle mode)
+
+```bash
+pip install abstractgateway
+```
+
+Bundle mode executes **WorkflowBundles** (`.flow`) via **WorkflowArtifacts** without importing `abstractflow`.
+
+### Optional (compatibility): VisualFlow JSON
+
+```bash
+pip install "abstractgateway[visualflow]"
+```
+
+This mode depends on the **AbstractFlow compiler library** (`abstractflow`) to interpret VisualFlow JSON (it does **not** require the AbstractFlow web UI/app).
+
+## Run
+
+```bash
+export ABSTRACTGATEWAY_DATA_DIR="./runtime"
+export ABSTRACTGATEWAY_FLOWS_DIR="/path/to/bundles-or-flow"
+
+# Security (recommended)
+export ABSTRACTGATEWAY_AUTH_TOKEN="your-token"
+export ABSTRACTGATEWAY_ALLOWED_ORIGINS="*"
+
+abstractgateway serve --host 127.0.0.1 --port 8080
+```
+
+Notes:
+- `ABSTRACTGATEWAY_WORKFLOW_SOURCE` defaults to `bundle`. Valid values:
+  - `bundle` (default): `ABSTRACTGATEWAY_FLOWS_DIR` points to a directory containing `*.flow` bundles (or a single `.flow` file)
+  - `visualflow` (compat): `ABSTRACTGATEWAY_FLOWS_DIR` points to a directory containing `*.json` VisualFlow files
+- For production, run behind HTTPS (reverse proxy) and set exact allowed origins.
+
+## Creating a `.flow` bundle (authoring)
+
+Use AbstractFlow to pack a bundle:
+
+```bash
+abstractflow bundle pack /path/to/root.json --out /path/to/bundles/my.flow --flows-dir /path/to/flows
+```
+
+## Starting a run (bundle mode)
+
+The stable way is to pass `bundle_id` + `flow_id`:
+
+```bash
+curl -sS -X POST "http://localhost:8080/api/gateway/runs/start" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-token" \
+  -d '{"bundle_id":"my-bundle","flow_id":"ac-echo","input_data":{}}'
+```
+
+For backwards-compatible clients, you can also pass a namespaced id as `flow_id` (`"my-bundle:ac-echo"`).
+
+## Docs
+- Architecture: `docs/architecture.md` (framework) and `abstractgateway/docs/architecture.md` (this package)
+- Deployment: `docs/guide/deployment.md`
+
+

abstractgateway-0.1.0/README.md

@@ -0,0 +1,83 @@
+# AbstractGateway
+
+AbstractGateway is the **deployable Run Gateway host** for AbstractRuntime runs:
+- durable command inbox
+- ledger replay/stream
+- security baseline (token + origin + limits)
+
+This decouples the gateway service from any specific UI (AbstractFlow, AbstractCode, web/PWA thin clients).
+
+## What it does (contract)
+- Clients **act** by submitting durable commands: `start`, `resume`, `pause`, `cancel`, `emit_event`
+- Clients **render** by replaying/streaming the durable ledger (cursor-based, replay-first)
+
+Endpoints:
+- `POST /api/gateway/runs/start`
+- `GET /api/gateway/runs/{run_id}`
+- `GET /api/gateway/runs/{run_id}/ledger`
+- `GET /api/gateway/runs/{run_id}/ledger/stream` (SSE)
+- `POST /api/gateway/commands`
+
+## Install
+
+### Default (bundle mode)
+
+```bash
+pip install abstractgateway
+```
+
+Bundle mode executes **WorkflowBundles** (`.flow`) via **WorkflowArtifacts** without importing `abstractflow`.
+
+### Optional (compatibility): VisualFlow JSON
+
+```bash
+pip install "abstractgateway[visualflow]"
+```
+
+This mode depends on the **AbstractFlow compiler library** (`abstractflow`) to interpret VisualFlow JSON (it does **not** require the AbstractFlow web UI/app).
+
+## Run
+
+```bash
+export ABSTRACTGATEWAY_DATA_DIR="./runtime"
+export ABSTRACTGATEWAY_FLOWS_DIR="/path/to/bundles-or-flow"
+
+# Security (recommended)
+export ABSTRACTGATEWAY_AUTH_TOKEN="your-token"
+export ABSTRACTGATEWAY_ALLOWED_ORIGINS="*"
+
+abstractgateway serve --host 127.0.0.1 --port 8080
+```
+
+Notes:
+- `ABSTRACTGATEWAY_WORKFLOW_SOURCE` defaults to `bundle`. Valid values:
+  - `bundle` (default): `ABSTRACTGATEWAY_FLOWS_DIR` points to a directory containing `*.flow` bundles (or a single `.flow` file)
+  - `visualflow` (compat): `ABSTRACTGATEWAY_FLOWS_DIR` points to a directory containing `*.json` VisualFlow files
+- For production, run behind HTTPS (reverse proxy) and set exact allowed origins.
+
+## Creating a `.flow` bundle (authoring)
+
+Use AbstractFlow to pack a bundle:
+
+```bash
+abstractflow bundle pack /path/to/root.json --out /path/to/bundles/my.flow --flows-dir /path/to/flows
+```
+
+## Starting a run (bundle mode)
+
+The stable way is to pass `bundle_id` + `flow_id`:
+
+```bash
+curl -sS -X POST "http://localhost:8080/api/gateway/runs/start" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-token" \
+  -d '{"bundle_id":"my-bundle","flow_id":"ac-echo","input_data":{}}'
+```
+
+For backwards-compatible clients, you can also pass a namespaced id as `flow_id` (`"my-bundle:ac-echo"`).
+
+## Docs
+- Architecture: `docs/architecture.md` (framework) and `abstractgateway/docs/architecture.md` (this package)
+- Deployment: `docs/guide/deployment.md`
+
+

abstractgateway-0.1.0/docs/architecture.md

@@ -0,0 +1,71 @@
+# AbstractGateway — Architecture (Living)
+
+> Updated: 2026-01-08  
+> Status: implemented (see completed backlog 318)
+
+AbstractGateway is the **deployable control-plane host** for AbstractRuntime runs:
+- clients submit **durable commands** (start/resume/pause/cancel/emit_event)
+- clients render by replaying/streaming the **append-only ledger** (cursor-based)
+- the gateway host owns the durable stores and is the single authority for a run (ADR‑0020)
+
+## Diagram (v0)
+
+```mermaid
+flowchart LR
+  subgraph Clients["Clients (stateless thin UIs)"]
+    ACode["AbstractCode (TUI)"]
+    Web["Web/PWA Thin Client"]
+    FlowUI["AbstractFlow UI"]
+    Third["3rd-party apps"]
+  end
+
+  subgraph GW["AbstractGateway (service)"]
+    API["HTTP API + SSE\n/api/gateway/*"]
+    Inbox["Durable Command Inbox\n(CommandStore)"]
+    Runner["GatewayRunner\npoll + tick"]
+    Stores["RunStore / LedgerStore / ArtifactStore"]
+  end
+
+  subgraph RT["AbstractRuntime (kernel)"]
+    Runtime["Runtime.tick / resume"]
+  end
+
+  Clients -->|commands| API
+  API --> Inbox
+  API -->|ledger replay/stream| Stores
+  Inbox --> Runner
+  Runner --> Runtime
+  Runtime --> Stores
+```
+
+## Scope and packaging
+AbstractGateway should be deployable without installing authoring tools (AbstractFlow).
+Workflow loading must therefore be pluggable:
+- core `abstractgateway` depends on `abstractruntime`
+- default workflow source: **WorkflowBundles (.flow)** containing **VisualFlow JSON** (`manifest.flows`), compiled via `abstractruntime.visualflow_compiler` (no `abstractflow` import)
+- optional extras can add additional workflow sources (e.g. a “directory of VisualFlow JSON files” host wired with authoring-side helpers)
+
+Bundle-mode execution wiring:
+- VisualFlow is compiled via `abstractruntime.visualflow_compiler` (single semantics engine).
+- LLM/tool workflows are supported by wiring `abstractruntime.integrations.abstractcore`:
+  - `LLM_CALL` handler (AbstractCore-backed)
+  - `TOOL_CALLS` handler (host-configured tool executor)
+- Visual Agent nodes are supported by registering deterministic per-node ReAct workflows (requires `abstractagent`).
+- Visual “On Event” nodes are supported by compiling derived listener workflows and starting them as child runs in the same session.
+
+Runtime configuration (env):
+- `ABSTRACTGATEWAY_PROVIDER` / `ABSTRACTGATEWAY_MODEL`: default provider/model for bundle-mode runs that contain LLM nodes.
+- `ABSTRACTGATEWAY_TOOL_MODE`:
+  - `passthrough` (default): tool calls enter a durable wait (safest for untrusted hosts)
+  - `local`: tool calls execute in the gateway process (dev only)
+
+Run start identifiers (bundle mode):
+- The **bundle** is the portable distribution unit. Clients should primarily identify “what to run” via `bundle_id`.
+- The **flow id** selects *which entrypoint/subflow* within the bundle to start:
+  - If a bundle has a single `manifest.entrypoints[]` item **or** declares `manifest.default_entrypoint`, the gateway can start it with `{bundle_id, input_data}` (no `flow_id`).
+  - If the bundle has multiple entrypoints and no `default_entrypoint`, clients must specify `flow_id` (or pass a fully-qualified workflow id like `bundle:flow`).
+
+## Related
+- Backlog 318: `docs/backlog/completed/318-framework-abstractgateway-extract-run-gateway-host.md`
+- ADR‑0018: `docs/adr/0018-durable-run-gateway-and-remote-host-control-plane.md`
+- ADR‑0020: `docs/adr/0020-agent-host-pool-and-orchestrator-placement.md`

abstractgateway-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "abstractgateway"
+version = "0.1.0"
+description = "AbstractGateway: deployable Run Gateway host for AbstractRuntime (commands + ledger)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Laurent-Philippe Albou" }]
+
+dependencies = [
+  "abstractruntime>=0.4.0",
+  "fastapi>=0.100.0",
+  "uvicorn[standard]>=0.23.0",
+]
+
+[project.optional-dependencies]
+# Optional support for starting runs from VisualFlow JSON (compiled via AbstractFlow).
+visualflow = [
+  "abstractflow>=0.3.0",
+]
+dev = [
+  "pytest>=7.0.0",
+  "httpx>=0.27.0",
+]
+
+[project.scripts]
+abstractgateway = "abstractgateway.cli:main"
+
+[project.urls]
+"GitHub" = "https://github.com/lpalbou/abstractgateway"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/abstractgateway"]
+
+

abstractgateway-0.1.0/src/abstractgateway/__init__.py

@@ -0,0 +1,11 @@
+"""AbstractGateway.
+
+AbstractGateway is a deployable Run Gateway host for AbstractRuntime:
+- durable command inbox (start/resume/pause/cancel/emit_event)
+- ledger replay + SSE streaming (replay-first)
+- security middleware for network-safe deployments
+"""
+
+__version__ = "0.1.0"
+
+

abstractgateway-0.1.0/src/abstractgateway/app.py

@@ -0,0 +1,55 @@
+"""AbstractGateway FastAPI application."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .routes import gateway_router
+from .security import GatewaySecurityMiddleware, load_gateway_auth_policy_from_env
+
+
+@asynccontextmanager
+async def _lifespan(_app: FastAPI):
+    # Start the background worker that polls the durable command inbox and ticks runs.
+    from .service import start_gateway_runner, stop_gateway_runner
+
+    start_gateway_runner()
+    try:
+        yield
+    finally:
+        stop_gateway_runner()
+
+
+app = FastAPI(
+    title="AbstractGateway",
+    description="Durable Run Gateway for AbstractRuntime (commands + ledger replay/stream).",
+    version="0.1.0",
+    lifespan=_lifespan,
+)
+
+# Gateway security (backlog 309).
+app.add_middleware(GatewaySecurityMiddleware, policy=load_gateway_auth_policy_from_env())
+
+# CORS for browser clients. In production, prefer configuring exact origins and terminating TLS at a reverse proxy.
+#
+# IMPORTANT: add after GatewaySecurityMiddleware so CORS headers are present even on early security rejections
+# (otherwise browsers surface a generic "NetworkError").
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(gateway_router, prefix="/api")
+
+
+@app.get("/api/health")
+async def health_check():
+    return {"status": "healthy", "service": "abstractgateway"}
+
+

abstractgateway-0.1.0/src/abstractgateway/cli.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import argparse
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="abstractgateway", description="AbstractGateway (Run Gateway host)")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    serve = sub.add_parser("serve", help="Run the AbstractGateway HTTP/SSE server")
+    serve.add_argument("--host", default="127.0.0.1", help="Bind host (default: 127.0.0.1)")
+    serve.add_argument("--port", type=int, default=8080, help="Bind port (default: 8080)")
+    serve.add_argument("--reload", action="store_true", help="Enable auto-reload (dev only)")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "serve":
+        import uvicorn
+
+        uvicorn.run(
+            "abstractgateway.app:app",
+            host=str(args.host),
+            port=int(args.port),
+            reload=bool(args.reload),
+        )
+        return
+
+    raise SystemExit(2)
+
+

abstractgateway-0.1.0/src/abstractgateway/config.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _as_bool(raw: Any, default: bool) -> bool:
+    if raw is None:
+        return default
+    if isinstance(raw, bool):
+        return raw
+    s = str(raw).strip().lower()
+    if not s:
+        return default
+    if s in {"1", "true", "yes", "on"}:
+        return True
+    if s in {"0", "false", "no", "off"}:
+        return False
+    return default
+
+
+def _as_int(raw: Optional[str], default: int) -> int:
+    if raw is None or not str(raw).strip():
+        return default
+    try:
+        return int(str(raw).strip())
+    except Exception:
+        return default
+
+
+def _as_float(raw: Optional[str], default: float) -> float:
+    if raw is None or not str(raw).strip():
+        return default
+    try:
+        return float(str(raw).strip())
+    except Exception:
+        return default
+
+
+def _env(name: str, fallback: Optional[str] = None) -> Optional[str]:
+    v = os.getenv(name)
+    if v is not None and str(v).strip():
+        return v
+    if fallback:
+        v2 = os.getenv(fallback)
+        if v2 is not None and str(v2).strip():
+            return v2
+    return None
+
+
+@dataclass(frozen=True)
+class GatewayHostConfig:
+    """Process-level configuration for the AbstractGateway host."""
+
+    data_dir: Path
+    flows_dir: Path
+
+    runner_enabled: bool = True
+    poll_interval_s: float = 0.25
+    command_batch_limit: int = 200
+    tick_max_steps: int = 100
+    tick_workers: int = 2
+    run_scan_limit: int = 200
+
+    @staticmethod
+    def from_env() -> "GatewayHostConfig":
+        # NOTE: We intentionally use ABSTRACTGATEWAY_* as the canonical namespace.
+        # For a transition period, we accept legacy ABSTRACTFLOW_* names as fallbacks.
+        data_dir_raw = _env("ABSTRACTGATEWAY_DATA_DIR", "ABSTRACTFLOW_RUNTIME_DIR") or "./runtime"
+        flows_dir_raw = _env("ABSTRACTGATEWAY_FLOWS_DIR", "ABSTRACTFLOW_FLOWS_DIR") or "./flows"
+
+        enabled_raw = _env("ABSTRACTGATEWAY_RUNNER", "ABSTRACTFLOW_GATEWAY_RUNNER") or "1"
+        runner_enabled = _as_bool(enabled_raw, True)
+
+        poll_s = _as_float(_env("ABSTRACTGATEWAY_POLL_S", "ABSTRACTFLOW_GATEWAY_POLL_S"), 0.25)
+        tick_workers = _as_int(_env("ABSTRACTGATEWAY_TICK_WORKERS", "ABSTRACTFLOW_GATEWAY_TICK_WORKERS"), 2)
+        tick_steps = _as_int(_env("ABSTRACTGATEWAY_TICK_MAX_STEPS", "ABSTRACTFLOW_GATEWAY_TICK_MAX_STEPS"), 100)
+        batch = _as_int(_env("ABSTRACTGATEWAY_COMMAND_BATCH_LIMIT", "ABSTRACTFLOW_GATEWAY_COMMAND_BATCH_LIMIT"), 200)
+        scan = _as_int(_env("ABSTRACTGATEWAY_RUN_SCAN_LIMIT", "ABSTRACTFLOW_GATEWAY_RUN_SCAN_LIMIT"), 200)
+
+        return GatewayHostConfig(
+            data_dir=Path(data_dir_raw).expanduser().resolve(),
+            flows_dir=Path(flows_dir_raw).expanduser().resolve(),
+            runner_enabled=bool(runner_enabled),
+            poll_interval_s=float(poll_s),
+            command_batch_limit=max(1, int(batch)),
+            tick_max_steps=max(1, int(tick_steps)),
+            tick_workers=max(1, int(tick_workers)),
+            run_scan_limit=max(1, int(scan)),
+        )
+
+

abstractgateway-0.1.0/src/abstractgateway/hosts/__init__.py

@@ -0,0 +1,6 @@
+from .visualflow_host import VisualFlowGatewayHost
+from .bundle_host import WorkflowBundleGatewayHost
+
+__all__ = ["VisualFlowGatewayHost", "WorkflowBundleGatewayHost"]
+
+