# AbstractFramework
> Meta-package + documentation hub for the AbstractFramework ecosystem (durable, observable agents/workflows).

This repo pins ecosystem package versions and provides a tiny helper API in `abstractframework/`.
Most runtime behavior lives in the individual package repos (AbstractCore/Runtime/Agent/Flow/Gateway/Code).

Quick commands:
- Install pinned stack: `pip install abstractframework`
- Check install health: `abstractframework doctor`
- Print installer manifest: `abstractframework manifest`
- Show detected component versions: `python -c "from abstractframework import print_status; print_status()"`

Notes for LLMs working in this repo:
- Prefer `docs/` as the ecosystem-level source of truth.
- Keep changes minimal and ecosystem-level (docs + version pins).
- If you need to change runtime behavior, you likely want the relevant package repo instead of this meta repo.
- Gateway-first hosted browser setups use Gateway user auth, opaque browser
  sessions, and `/console` for account/admin/defaults management. AbstractFlow,
  AbstractCode Web, and AbstractObserver exchange user tokens for app-scoped
  browser sessions and do not persist bearer tokens in browser settings.
  Gateway login responses do not expose session ids/CSRF tokens in JSON, and
  default resolution is Core defaults -> Gateway baseline Core config ->
  per-runtime Core config override.
  Do not treat the bootstrap `ABSTRACTGATEWAY_AUTH_TOKEN` as a browser-user
  login token. Gateway session cookies are HTTP-only for the session id, use a
  separate CSRF cookie, set `Secure` only under HTTPS, expire, logout cleanly,
  and are revoked when the backing user is disabled/deleted/token-rotated.
- Gateway user isolation is enforced through per-principal runtime routing plus
  a central route-family policy. Ordinary users can use their own runs, ledgers,
  artifacts, KG/session memory, private workflows, session artifacts,
  prompt-cache session names, and runtime-scoped Core defaults. Admin-only workspace
  helpers/import/export and provider prompt-cache controls are advertised as
  unavailable in discovery with machine-readable `admin_required` metadata.
  Deleting a user reserves the retained runtime id for that principal so the
  runtime cannot be reassigned to a different same-tenant user while data is
  still retained. Admins may explicitly transfer a retained runtime to an
  existing same-tenant user or purge the retained runtime directory before
  releasing the runtime id for reuse.
- Gateway provider connections are Gateway-owned reusable profiles for OpenAI,
  Anthropic, OpenRouter, Portkey, LM Studio, Ollama, and custom
  OpenAI-compatible endpoints. They include a description, provider family,
  base URL, optional model allowlist, and a write-only API key. Discovery
  exposes them as virtual providers such as `endpoint:office-vllm`; Runtime
  resolves the virtual id into transient provider/base URL/key parameters
  without storing secrets in workflow JSON or browser storage.
- AbstractCore also supports local single-principal provider endpoint profiles
  through `abstractcore config set-provider ...`. These profiles expose the
  same virtual provider shape (`endpoint:<id>`) for Core-only developers, while
  Gateway remains responsible for hosted user/runtime scoping.
- Gateway Console separates provider configuration from defaults: the Providers
  tab stores endpoint URLs/API keys and tests discovery; the Defaults tab only
  maps capability routes to configured virtual providers and discovered models.
  LLM/embedding model pickers use Core `capability_route` filters such as
  `input.image,output.text` and `embedding.text`; generated-media defaults use
  capability plugin catalogs.
- AbstractFlow uses the same route-aware discovery for text model selectors and
  Models Catalog nodes. Gateway `/runs/start` accepts optional `thinking`, and
  Flow LLM Call/Agent nodes can set or pin `thinking` so reasoning controls
  flow through Runtime and AbstractAgent into Core.
- Hosted Flow, Code Web, and Observer use the server-configured Gateway URL on
  non-loopback UI hostnames. Browser-supplied Gateway URL changes are rejected
  unless the app-specific remote override is enabled behind access control.
  Host checks trust `Host` by default; forwarded host headers require an
  explicit trust-proxy env setting.
- Gateway workflow sharing uses the explicit workflow catalog, not another
  user's private `/bundles` directory. Catalog bundle versions are immutable,
  admins move default pointers and ACLs, and users start catalog workflows with
  `registry_scope: "tenant_catalog"` so the run executes in their own runtime.
  Catalog scope is explicit, direct private-bundle routes reject
  catalog-internal ids, and Gateway signs catalog workflow policy before
  passing it to Runtime.

## Start Here

- [README.md](README.md): Ecosystem overview and install paths.
- [docs/README.md](docs/README.md): Docs index for this repo.
- [docs/install.md](docs/install.md): Light / Apple / GPU install chooser and generated manifest contract.
- [docs/getting-started.md](docs/getting-started.md): Practical entry paths (core, runtime, gateway, UIs, bundles).
- [docs/architecture.md](docs/architecture.md): How the stack fits together.
- [docs/glossary.md](docs/glossary.md): Shared terminology used across docs.
- [docs/adr/README.md](docs/adr/README.md): Cross-package ADR index and accepted platform contracts.

## Scenarios

- [docs/scenarios/README.md](docs/scenarios/README.md): Scenarios index.
- [docs/scenarios/offline-coding-assistant.md](docs/scenarios/offline-coding-assistant.md): Local durable coding assistant.
- [docs/scenarios/gateway-first-local-dev.md](docs/scenarios/gateway-first-local-dev.md): Local gateway + web UIs.
- [docs/scenarios/specialized-agent-flow.md](docs/scenarios/specialized-agent-flow.md): Portable `.flow` agent across clients.
- [docs/scenarios/workflow-bundle-lifecycle.md](docs/scenarios/workflow-bundle-lifecycle.md): Publish/install/deprecate bundles.
- [docs/scenarios/phone-thin-client.md](docs/scenarios/phone-thin-client.md): iPhone via Web/PWA + gateway.
- [docs/scenarios/telegram-permanent-contact.md](docs/scenarios/telegram-permanent-contact.md): Telegram bridge + workflow.
- [docs/scenarios/email-inbox-agent.md](docs/scenarios/email-inbox-agent.md): Email bridge + workflow.

## Guides

- [docs/guide/README.md](docs/guide/README.md): Guides index.
- [docs/guide/deployment-topologies.md](docs/guide/deployment-topologies.md): Supported deployment patterns.
- [docs/guide/deployment-web.md](docs/guide/deployment-web.md): Browser UIs and gateway setup.
- [docs/guide/deployment-iphone.md](docs/guide/deployment-iphone.md): iPhone/PWA notes.
- [docs/guide/gateway-security.md](docs/guide/gateway-security.md): Safe gateway exposure defaults.
- [docs/guide/capability-routing-defaults.md](docs/guide/capability-routing-defaults.md): Provider/model/base URL defaults for input, output, embedding, and rerank routes.
- [docs/guide/runtime-artifacts.md](docs/guide/runtime-artifacts.md): Runtime artifact descriptors, Gateway artifact search, Observer views, ledger/KG boundaries, and safe retrieval practice.
- [docs/guide/workflow-bundles.md](docs/guide/workflow-bundles.md): `.flow` bundles and lifecycle.
- [docs/guide/agent-skills.md](docs/guide/agent-skills.md): Agent Skills (SKILL.md) proposal and how it composes with flows.
- [docs/guide/process-manager-env-vars.md](docs/guide/process-manager-env-vars.md): Write-only env var config from Observer.

## Release Profile (Pinned Versions)

- [pyproject.toml](pyproject.toml): Single source of truth for pinned ecosystem versions and extras.
- [abstractframework/__init__.py](abstractframework/__init__.py): `RELEASE_VERSIONS`, `get_release_profile()`, `print_status()`.

## Full Context

- [llms-full.txt](llms-full.txt): Concatenated context for copy/paste into an LLM (`python scripts/gen_llms_full.py`).

## Proposals / Research (non-canonical)

- [docs/backlog/overview.md](docs/backlog/overview.md): Root backlog index and active cross-package work.
- [docs/backlog/completed/0141_flow_browser_session_gateway_auth.md](docs/backlog/completed/0141_flow_browser_session_gateway_auth.md): Completed Flow browser-session Gateway auth isolation.
- [docs/backlog/planned/0142_gateway_tenant_isolation_and_shared_runtime.md](docs/backlog/planned/0142_gateway_tenant_isolation_and_shared_runtime.md): Planned Gateway tenant isolation and shared runtime design.
- [docs/backlog/planned/0143_shared_gateway_per_principal_runtime_router.md](docs/backlog/planned/0143_shared_gateway_per_principal_runtime_router.md): In-progress shared Gateway per-principal runtime router work.
- [docs/backlog/planned/gateway-control-plane/README.md](docs/backlog/planned/gateway-control-plane/README.md): Gateway admin/config/workflow-permission control-plane backlog track.
- [docs/backlog/proposed/gateway-control-plane/README.md](docs/backlog/proposed/gateway-control-plane/README.md): Proposed Explorer/Manager package-boundary follow-ups.
- [docs/backlog/completed/0154_multi_user_security_release_blockers.md](docs/backlog/completed/0154_multi_user_security_release_blockers.md): Completed multi-user release-blocking security fixes.
- [docs/backlog/completed/0157_gateway_provider_endpoint_profiles.md](docs/backlog/completed/0157_gateway_provider_endpoint_profiles.md): Completed Gateway-owned provider endpoint profiles and virtual `endpoint:*` discovery.
- [docs/backlog/planned/0164_gateway_docker_ghcr_deployment_track.md](docs/backlog/planned/0164_gateway_docker_ghcr_deployment_track.md): Planned Gateway Docker/GHCR deployment track for light and GPU images.
- [docs/backlog/proposed/gateway-control-plane/0155_hosted_proxy_shared_helper_extraction.md](docs/backlog/proposed/gateway-control-plane/0155_hosted_proxy_shared_helper_extraction.md): Proposed threshold for extracting shared hosted proxy helpers.
- [docs/backlog/planned/074_agent_skills_integration.md](docs/backlog/planned/074_agent_skills_integration.md): Backlog item for Agent Skills integration.
- [docs/backlog/planned/074_agent_skills_integration_plan.md](docs/backlog/planned/074_agent_skills_integration_plan.md): Phased plan for Agent Skills integration.
- [docs/skills/](docs/skills/): Research notes (spec links + ecosystem scan) for Agent Skills.
- [docs/claude/](docs/claude/): Research notes about Claude (non-Agent-Skills capability/skills scan).

## Optional

- [AbstractCore](https://github.com/lpalbou/abstractcore): LLM providers, tools, structured output, media.
- [AbstractRuntime](https://github.com/lpalbou/abstractruntime): Durable execution (runs, effects, waits, ledger, stores).
- [AbstractAgent](https://github.com/lpalbou/abstractagent): Agent patterns (ReAct/CodeAct/MemAct) built on runtime + core.
- [AbstractFlow](https://github.com/lpalbou/abstractflow): npm web editor for VisualFlow authoring on top of AbstractGateway.
- [AbstractGateway](https://github.com/lpalbou/abstractgateway): HTTP/SSE control plane for gateway-first deployments.
- [AbstractCode](https://github.com/lpalbou/abstractcode): Terminal + web host UIs for durable runs.
