ygg-agent
Run an LLM agent on PostgreSQL with no MCP. The model writes SQL; the database decides.
ygg-agent is the loop between a language model and a PostgreSQL that runs
pg_agent_gate. The model writes one SQL
statement; the gate verifies it against PostgreSQL itself, runs it under the agent's own
limits, and records it; the verdict goes back to the model; repeat. There is no MCP server,
no tool schema in the model's context, and no JSON between the model and its data: the model
writes SQL, which is what it knows best, over PostgreSQL's own protocol.
pip install "ygg-agent[binary]" # or: uv add ygg-agent
from ygg_agent import Agent, OpenAICompatible
agent = Agent(
OpenAICompatible("http://127.0.0.1:8080/v1"), # any /v1/chat/completions server
dsn="postgresql://billing_agent:...@db.internal/app", # a role registered as an agent
)
result = agent.run("Mark order 4 as cancelled.")
result.outcome # done | pending | refused | gave_up
for step in result.steps:
print(step.verdict, step.sql) # kept, read, refused, aborted ...
Why no MCP
Measured with the same model (a plain Qwen3-8B, no fine-tuning), the same 13 tasks (7 of them traps) and a superuser checking what really changed, on a CPU-only CI runner anyone can re-run (the run; agent-gate-demo/compare, one command):
- With the same gate behind both, this loop used 5x fewer prompt tokens than the model reaching the gate through MCP (24k vs 126k for the 13 tasks) and finished each task 13x faster (a median of 14 s against 185 s).
- Through a popular Postgres MCP server, with the same privileges, 4 of 7 traps broke out (12 of 21 over three runs). With the database deciding: none.
The safety comes from the database deciding, not from the transport -- so the loop that keeps the model closest to SQL is also the cheapest.
What it guarantees, and how
- It only runs behind the gate. On connect it asks
agent_gate.whoami(), and refuses to work unless the session is an enforced agent session. A superuser, an application role, or a role thatSET ROLEd into the agent's is not behind the gate -- and would run anything -- soAgentraisesNotBehindGateinstead. Connect as the registered agent role. - It never executes the model's SQL itself. The statement travels as an argument to
agent_gate.propose(); the database decides whether it runs (commit) or only shows its effect (dry_run). - It stops probing. After
max_refusals(default 3) refusals or aborts in a row the run ends withoutcome="refused". Measured: "delete every item" against a limit of 3 rows went from eight ever-widerDELETEs to three -- 609 prompt tokens instead of 2,954 -- with the same result: nothing deleted. - The model sees the real catalog. The relations, columns, keys and privileges come from
agent_gate.discover()-- what this agent may touch, from the live catalog.
Modes
mode="commit"(default): every statement the gate accepts is committed; reads return rows, which go back to the model.mode="dry_run": nothing is kept. The first write the gate accepts comes back asresult.pending, with the exact rows it would change, for a person to commit -- or foragent_gate.approve()and a commit when the agent is registered withrequires_approval.
Events
Every proposal, refusal, kept write, read and stop is an Event handed to the on_event
callbacks -- the place for an audit sink, an approval queue, or a fleet control plane:
agent = Agent(model, dsn=dsn, on_event=[lambda e: print(e.kind, e.proposal, e.reason)])
The gate keeps its own append-only record either way (agent_gate_internal.executions).
Models
OpenAICompatible speaks /v1/chat/completions: llama.cpp, vLLM, Ollama, OpenAI and most
gateways. user_suffix=" /no_think" turns off Qwen3's reasoning; extra_body passes
server-specific fields. Anything with a complete(messages) -> Completion method works;
ScriptedModel replays fixed answers for tests.
The model in this process: no HTTP at all
LlamaCpp (0.2.0) loads a GGUF file and computes the tokens in the agent's own process,
through llama-cpp-python. There is no model
server to start and no HTTP request: the model writes SQL here, and the only connection the
agent opens is PostgreSQL's.
pip install "ygg-agent[binary,local]"
from ygg_agent import Agent, LlamaCpp
agent = Agent(
LlamaCpp("/models/qwen3-8b-q4_k_m.gguf", n_gpu_layers=-1, user_suffix=" /no_think"),
dsn="postgresql://billing_agent:...@db.internal/app",
)
n_gpu_layers=0 (the default) computes on the CPU and -1 puts every layer on the GPU;
lora_path applies an adapter; grammar takes a GBNF grammar the sampler must follow token
by token, such as one pg_grammar_guard compiles
from the live catalog. The model is loaded on the first completion and kept, and one
completion runs at a time.
What this changes and what it does not: the gate's guarantees are the same with either
class, because they come from the database. LlamaCpp removes the model server and its
HTTP hop, so the whole loop is one process and one PostgreSQL connection. It costs that
process the model's memory, and a crash inside llama.cpp ends the agent, not the database.
tests/test_model.py checks it with a stand-in for llama-cpp-python, and, when
YGG_AGENT_TEST_GGUF names a real model, with the real one while every Internet socket
refuses to connect.
Requirements
Python 3.10+, psycopg 3, and a PostgreSQL with pg_agent_gate 0.4.0 or later and an agent
registered with agent_gate.register_agent(). The quickest way to have one:
podman run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret ghcr.io/latamflows/ygg-pg:0.3.6
Tests
YGG_AGENT_TEST_DSN=postgresql://postgres:secret@127.0.0.1:5432/postgres uv run --group dev pytest
YGG_AGENT_TEST_GGUF=/models/some.gguf uv run --group dev --extra local pytest tests/test_model.py
The tests create their own database and agent, play the model with ScriptedModel, and check
every claim from a superuser connection: what was kept, what was refused, that the budget holds
across turns, that a SET ROLE session is refused, that each act is in the gate's record.
examples/live.py runs a real model against a real database.
License
Apache-2.0. See LICENSE and NOTICE. "pg_agent_gate" and "ygg" are names, not licensed with the code (Apache License 2.0, section 6).
Metadata
Release files for ygg-agent 0.2.0
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 |
|---|---|---|---|---|
| ygg_agent-0.2.0.tar.gz | 22.4 kB | Without provenance | Details for ygg_agent-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ygg_agent-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for ygg_agent-0.2.0-py3-none-any.whl |
Total release size: 40.9 kB
Release files / ygg_agent-0.2.0.tar.gz
| Download URL | ygg_agent-0.2.0.tar.gz |
|---|---|
| Size | 22.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
25e1d3a7a8e30dccd2870d4c66c383cabcc021787575aaa05611eb184234fc68
|
|
BLAKE2b-256 checksum How to use checksums |
67ebe18913093988e2ab3c02c253fbcda7070d610625aaf2e018976cbf0ba3fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ygg_agent-0.2.0-py3-none-any.whl
| Download URL | ygg_agent-0.2.0-py3-none-any.whl |
|---|---|
| Size | 18.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d08b2f8855f7fb27c6a1d7b8604d22ae126ffc78705734b70451b02e11d74e6f
|
|
BLAKE2b-256 checksum How to use checksums |
735d6fb88ccbf5a14bc140930bfa981ab406d12e9d8a6cc24c41068a0c3d2b63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for ygg-agent 0.2.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.