Skip to main content

quebragalho-sdk

Run the Quebra-Galho (qg) coding agent from Python. Requires Python ≥ 3.9 and the qg binary (npm i -g @quebragalho-dev/cli). No dependencies.

from quebragalho import QG

qg = QG(cwd="/path/to/repo")

# One shot
result = qg.run("Explain what this repo does", model="kimi-k3", plan=True)
print(result.text, result.usage.total_tokens)

# Streaming
with qg.stream("Fix the failing test", auto="medium") as run:
    for event in run:
        if event["type"] == "text":
            print(event["delta"], end="")
    done = run.result()  # RunResult

# asyncio
result = await qg.arun("...")
run = await qg.astream("...")
async for event in run: ...

API

  • QG(binary=None, api_key=None, cwd=None, env=None, **defaults) — binary defaults to $QG_BIN, then qg on PATH. api_key is sent as QG_API_KEY; omit it to use the stored login. Extra keyword arguments become default run options.
  • qg.run(prompt, **options) → RunResult; raises QGRunError on a non-success status. qg.arun is the asyncio version.
  • qg.stream(prompt, **options) → Run: iterable of event dicts (as in the protocol doc), plus result(), abort(), close(). qg.astream returns an AsyncRun.
  • prompt is a string or {"text": ..., "images": [{"mediaType": ..., "data": bytes}]}.
  • Options: model, cwd, mode, plan, auto, permission_mode, max_turns, reasoning_effort, exec_profile, enabled_tools, disabled_tools, add_dirs, resume (id or True), fork, session_title, worktree, dangerously_skip_permissions, extra_args. Unknown names raise TypeError.
  • Continue a conversation with resume=result.session_id.

Errors: QGRunError (exit_code, code, result, stderr), QGProtocolError, QGAbortError, QGBinaryNotFoundError, all extending QGError.

usage.cost_brl / usage.cost_usd sum the per-call prices from the QG catalog. They are None when no call could be priced (for example, a qg older than the field, or a model missing from the catalog).

Permissions

A headless run cannot answer approval prompts. By default (auto mode) sandboxed shell work, including writing files in the workspace, is allowed; actions such as network access are not. The blocked calls come back as result.permission_denials (PermissionDenial: id, tool, reason, risk_level, categories), and the model usually explains the failure in result.text. To allow more, pass permission_mode or auto="high" (which enables unsafe tools), or hand the model a narrower task. enabled_tools / disabled_tools restrict what it can try.

Metadata

Release files for quebragalho-sdk 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 quebragalho-sdk 0.2.0
File Size Uploaded Provenance Actions
quebragalho_sdk-0.2.0.tar.gz 10.7 kB With provenance Details for quebragalho_sdk-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for quebragalho-sdk 0.2.0
File Interpreter ABI Platform Actions
quebragalho_sdk-0.2.0-py3-none-any.whl Python 3 none any Details for quebragalho_sdk-0.2.0-py3-none-any.whl

Total release size: 20.6 kB

Release files / quebragalho_sdk-0.2.0.tar.gz

Download URL quebragalho_sdk-0.2.0.tar.gz
Size 10.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f2559e7b7e76bf5da227dab7271a0f16f8d5b18acb2f46dfe5fd770d89f839ac
BLAKE2b-256 checksum
How to use checksums
438f08af45e7cd5cfd7acb7447b6d9ec051858880b756fe65e4b281f7b12f7af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Release files / quebragalho_sdk-0.2.0-py3-none-any.whl

Download URL quebragalho_sdk-0.2.0-py3-none-any.whl
Size 9.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
351dcfdd150b2a1d1906cd6b9a866777a910ff1671990a43d96fe5c7eb6e8251
BLAKE2b-256 checksum
How to use checksums
d8d977576a23cf0a6b108b4f82f023376b65d1556450a56e8f1ffff6faddcbb9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 28, 2026.

Transparency log

Security for quebragalho-sdk 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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for quebragalho_sdk-0.2.0.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 Oct 28, 2026.

Transparency log

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 Full 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