Skip to main content

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 that SET ROLEd into the agent's is not behind the gate -- and would run anything -- so Agent raises NotBehindGate instead. 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 with outcome="refused". Measured: "delete every item" against a limit of 3 rows went from eight ever-wider DELETEs 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 as result.pending, with the exact rows it would change, for a person to commit -- or for agent_gate.approve() and a commit when the agent is registered with requires_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)

Source distribution for ygg-agent 0.2.0
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)

Table of built distributions (wheels) for ygg-agent 0.2.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page