Metadata-Version: 2.4
Name: grokbuildstreaming
Version: 0.1.3
Summary: Stream text from the signed-in Grok Build CLI
Author: Eliran Wong
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# grokbuildstreaming

Stream text from the [Grok Build](https://x.ai) CLI. This library is a text-completion alternative to [agentmake](https://github.com/eliranwong/agentmake): you pass chat messages, and it yields response text as the CLI produces it.

Authentication is the subscription session from `grok login` (`~/.grok/auth.json`). The child process does not receive `XAI_API_KEY`. No API key is read or sent.

## Install

```bash
pip install grokbuildstreaming
```

Published on [PyPI](https://pypi.org/project/grokbuildstreaming/). Requires the `grok` executable on `PATH` or at `~/.grok/bin/grok`, and a completed `grok login`.

## Stream

```python
import asyncio
from grokbuildstreaming import stream_text

async def main():
    messages = [
        {"role": "system", "content": "You are a concise Bible study assistant."},
        {"role": "user", "content": "What is John 3:16 about?"},
        {"role": "assistant", "content": "It states God's love for the world."},
    ]
    async for chunk in stream_text(messages, follow_up="Quote it briefly.", model="grok-4.7"):
        print(chunk, end="", flush=True)

asyncio.run(main())
```

`messages` use `role` and `content`, the same shape agentmake accepts. `follow_up` is the newest user turn. An explicit `system` argument is sent with `--system-prompt-override`. System messages already in `messages` stay in the user prompt, so a generic identity does not outrank that task. Each call is a new headless process: the library does not resume a previous Grok session.

The process is text-only. It runs with `--max-turns 1`, plan mode off, web search off, subagents off, and built-in tools removed, in a temporary working directory. Cancel an in-flight stream by setting the `asyncio.Event` passed as `cancel_event`.

`collect_text` returns the whole reply:

```python
from grokbuildstreaming import collect_text

text = await collect_text(follow_up="Reply with exactly: pong")
```
