This release is a pre-release and may not be stable for production use.
Gabby
An Agent Runtime and Governance Framework
Gabby helps developers define what an AI agent can do, govern how it uses tools, and execute each request within explicit limits. It combines reusable agent and skill definitions with policy checks, optional approvals and verification, bounded tool execution, and traceable results. Gabby is stateless between runs: the consuming application owns conversation history and durable user state.
Documentation · Architecture · Quick start · Contributing · Security
About
Gabby is for developers who need a consistent way to configure agent capabilities, govern tool access, and execute agent work. A host application supplies a request and any context or memory it wants the agent to use. Gabby validates the agent definition, applies its configured runtime contracts, executes model and tool calls within the configured bounds, and returns the output and optional trace. Execution state is temporary; persistence remains with the host by default.
To give an agent a requested character, the host defines its instructions and may supply user-scoped preferences or reference material. Gabby places that guidance in the model context while runtime policies enforce tool access and execution limits; the model still generates the response, so guidance alone cannot guarantee its tone or content. Gabby does not train models, modify model weights, or load model adapters.
Gabby is complementary to agent orchestration frameworks such as LangChain, CrewAI, and IBM BeeAI. Those frameworks help developers compose agents and workflows; Gabby focuses on the runtime boundary for a configured agent: enforcing tool permissions and policies, applying approvals and verification, bounding execution, and returning traceable results. Gabby does not aim to replace an application's orchestration layer. It can serve as the governed execution runtime for an agent or workflow selected and coordinated by the host application.
The runtime is asynchronous first, with synchronous convenience methods and a FastAPI service. The same agent definition can be used from Python or through the versioned HTTP API. Model providers, tools, retrieval, policy engines, verification, and tracing are replaceable through Python interfaces.
Gabby governs agent execution inside the runtime. It is not a hosted multi-tenant control plane, an identity-management system, or the owner of application conversations and durable memory. Host applications remain responsible for caller identity, long-term state, and deployment-level isolation. See the architecture and threat model for these boundaries.
Architecture
Host application
├── owns conversation history and durable state
└── sends request + selected context
↓
Gabby governance and execution runtime
├── resolved agent definition and skills
├── model provider and knowledge retrieval
├── policy checks and bounded tool execution
├── optional approvals and verification
└── bounded result and optional trace
↓
Host application
An agent definition composes a model, environment, skills, tools, knowledge sources, instructions, policies, and verification. At construction, Gabby validates and resolves configuration into an immutable execution plan. Each run receives its own transient state and ends with a result; it does not implicitly create a chat session or persistent memory. Stateless execution is the runtime's state-ownership model; governance and controlled tool execution are the product's central purpose.
Runtime capabilities
| Area | What Gabby provides |
|---|---|
| Execution | Async-first agent loop, sync wrappers, bounded steps and tool calls, deadlines, cancellation, optional planning and retries, per-run token and estimated cost circuit breakers |
| Models | OpenAI-compatible, Ollama, Hugging Face Inference Providers, Anthropic, Gemini |
| Skills | Reusable, composable skill definitions, dependency resolution, package and registry workflows, Ed25519 publisher signature verification required by default |
| Tools and policies | Schema-validated tools, explicit permissions, JWT scope-based RBAC, approval hooks, bounded results, runtime policy enforcement |
| Isolation | Optional per-run Docker or Podman sandboxing for supported shell/filesystem tools; configuration and host determine the effective boundary |
| Knowledge | Bounded plain-text and Markdown ingestion, SQLite FTS5 and vector stores, hybrid retrieval contracts, pluggable embeddings and reranking |
| Interfaces | Python API, FastAPI /v1 run and SSE endpoints, generated TypeScript/Node.js, Go, and Rust clients |
| Observability | Structured execution traces and injectable event tracing |
Review the starter bundle pack for source-reviewed support, SQL analyst, and sandboxed Git examples. Signed release artifacts require a maintainer-provisioned signing key. Optional prewarmed single-use containers are described in the scaling guide. Lightweight TypeScript, Go, and Rust HTTP/SSE clients are available under sdks/.
Gabby’s controls are not all enabled by default. Skill signing is optional, sandboxing requires explicit configuration, and host-provided tool handlers are trusted code unless a sandboxed implementation is supplied. Engine, operating-system, provider, and deployment behavior must be verified for the target environment. See the threat model, scaling and operational tradeoffs, and current limitations.
Quick start
Clone the repository and install Gabby from the checkout in editable mode. This installs the
distribution as gabby-ai, while the Python import and command-line tool remain gabby. Editable
installation means changes you make in this checkout are used immediately:
git clone https://github.com/undreamt-oss/gabby.git
cd gabby
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[server,auth]"
On Windows PowerShell, activate the environment with .\.venv\Scripts\Activate.ps1 instead of
source .venv/bin/activate.
To install the full contributor environment and run the checks, use the locked development setup:
uv sync --frozen --group dev --extra server --extra auth
uv run pytest
Create a starter agent and inspect its configuration:
gabby init --template customer-support ./agent.yaml
gabby validate ./agent.yaml
Edit agent.yaml to choose a model and configure the agent’s instructions, skills, tools, and policies. Keep credentials outside the file. For example, set the configured provider’s API key in the environment, then run:
export MODEL_API_KEY="..."
gabby run ./agent.yaml "Summarize this request"
In Windows PowerShell, set the variable with $env:MODEL_API_KEY = "..." before running Gabby.
The generated starter uses a placeholder model and grants no tools by default. Add the correct provider credential variable and explicitly register tools in the consuming application before granting them to an agent. See the complete user guide for provider-specific setup, configuration, tools, skills, knowledge, Python embedding, API serving, and deployment.
Project status
Gabby is pre-1.0 beta software (0.1.0b5). Public extension APIs may change before v1.0. Local tests and static checks establish only the behaviors they exercise; they do not certify a hosted deployment, every provider/model pairing, or every container host and engine combination. Review the release notes, readiness scorecard, and threat model before evaluating it for sensitive or production workloads.
Open source and contributing
See the runtime integrations guide for MCP, OpenTelemetry, signed audit, and orchestration adapters.
Gabby is maintained in the undreamt-oss organization. Contributions are welcome across runtime behavior, providers, documentation, examples, accessibility, security, and developer experience.
Before contributing, read the contributing guide, governance, and security policy. See the documentation index for architecture, extension contracts, operations, and release guidance.
Metadata
Release files for gabby-ai 0.1.0b5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gabby_ai-0.1.0b5.tar.gz | 426.1 kB | With provenance | Details for gabby_ai-0.1.0b5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gabby_ai-0.1.0b5-py3-none-any.whl | Python 3 | none | any | Details for gabby_ai-0.1.0b5-py3-none-any.whl |
Total release size: 702.3 kB
Release files / gabby_ai-0.1.0b5.tar.gz
| Download URL | gabby_ai-0.1.0b5.tar.gz |
|---|---|
| Size | 426.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8607b6c3bfb64be0cf3bdee1b3f2bebb65e6de3aeccede26c5cce1b303a461c8
|
|
BLAKE2b-256 checksum How to use checksums |
2dfee01424a19f4013bf7d9a1a75c1d0d486789c62d2fef58137ac822f66915a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / gabby_ai-0.1.0b5-py3-none-any.whl
| Download URL | gabby_ai-0.1.0b5-py3-none-any.whl |
|---|---|
| Size | 276.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c792ade36e23f44e2150090da867d77965bb6134d101e63cd94cbf863d0d9c3f
|
|
BLAKE2b-256 checksum How to use checksums |
40e1eed384912f3eaad790575aa83823107d8750808dd504cee971a12647b15f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for gabby-ai 0.1.0b5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for gabby_ai-0.1.0b5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.