User Guide¶

Donger is operated through a Streamlit interface. Launch it from the repository root with:

streamlit run app.py

Use the sidebar to select the active mode, provider model, runtime parameters, optional system instructions, and mode-specific controls.

Python Usage Examples¶

The examples below show how to use Donger's grok wrapper classes directly from Python. These examples assume they are run from the repository root or from an environment where the Donger source directory is on PYTHONPATH.

import config as cfg
from grok import (
    Chat,
    Images,
    Embeddings,
    TTS,
    Transcription,
    Translation,
    Files,
    FileSearch,
    CloudBuckets,
)

Most examples require a valid XAI API key configured through config.py or environment variables.

setx XAI_API_KEY "your-xai-api-key"
setx GOOGLE_API_KEY "your-google-api-key"

Restart PowerShell after using setx.

Chat¶

The Chat class supports text-generation workflows, including standard prompts, system instructions, grounding tools, URL context, and file-search-oriented requests where supported by the selected model.

Basic text generation¶

from grok import Chat

chat = Chat()

response = chat.generate_text(
    prompt="Explain the difference between budget authority, obligations, and outlays.",
    model=<grok model>,
    temperature=0.2,
    max_tokens=1000,
)

print(response)

Text generation with system instructions¶

from grok import Chat

chat = Chat()

response = chat.generate_text(
    prompt="Summarize the risks of operating under a continuing resolution.",
    model=<grok model>,
    temperature=0.2,
    max_tokens=1200,
    instruct=(
        "You are a federal budget analyst. Use precise appropriations terminology, "
        "distinguish budget authority from obligations and outlays, and answer in "
        "a concise executive briefing style."
    ),
)

print(response)

Build URL context before a request¶

from grok import Chat

chat = Chat()

urls = chat.build_urls(
    urls=[
        "https://www.whitehouse.gov/omb/",
        "https://home.treasury.gov/",
    ],
    max_urls=2,
)

response = chat.generate_text(
    prompt="Using the provided references, summarize the role of OMB and Treasury in federal budget execution.",
    model=<grok model>,
    temperature=0.2,
    max_tokens=1200,
    urls=urls,
)

print(response)

Check model-supported tools¶

from grok import Chat

chat = Chat()

tools = chat.get_supported_tools(<grok model>)

print(tools)

Images¶

The Images class supports image generation, image analysis, and image editing workflows.

Generate an image¶

from pathlib import Path
from grok import Images

images = Images()

image = images.generate(
    prompt=(
        "Create a dark-themed software architecture diagram for a Streamlit application "
        "that uses grok wrappers, SQLite persistence, document retrieval, and Google Cloud services."
    ),
    model="grok-2.5-flash-image",
    aspect="16:9",
    resolution="1K",
    response_modalities="image",
)

if image is not None:
    output_path = Path("docs/images/Donger-generated-architecture.png")
    output_path.parent.mkdir(parents=True, exist_ok=True)
    image.save(output_path)
    print(f"Saved image to {output_path}")

Analyze an image¶

from grok import Images

images = Images()

analysis = images.analyze(
    prompt=(
        "Review this architecture diagram for documentation quality. Identify missing labels, "
        "unclear relationships, and improvements for a technical audience."
    ),
    path="docs/images/Donger-architecture.png",
    model=<grok image model>,
    response_modalities="text",
)

print(analysis)

Edit an image¶

from pathlib import Path
from grok import Images

images = Images()

edited = images.edit(
    prompt=(
        "Improve text contrast, preserve the dark theme, make the layer boundaries clearer, "
        "and keep the diagram suitable for MkDocs documentation."
    ),
    path="docs/images/Donger-architecture.png",
    model=<grok image model>,,
    aspect="16:9",
    resolution="1K",
    response_modalities="image",
)

if edited is not None:
    output_path = Path("docs/images/Donger-architecture-edited.png")
    edited.save(output_path)
    print(f"Saved edited image to {output_path}")

TTS¶

The TTS class converts text into spoken audio.

Generate WAV bytes¶

from grok import TTS

tts = TTS()

audio_bytes = tts.create_speech(
    text="Donger is ready to support text, image, audio, document, and data workflows.",
    model=<grok audio model>,
    voice="Kore",
    format="audio/wav",
)

if audio_bytes is not None:
    print(f"Generated {len(audio_bytes)} bytes.")

Generate and save a WAV file¶

from grok import TTS

tts = TTS()

output_path = tts.create_speech(
    text="This is a generated audio briefing from Donger.",
    filepath="outputs/Donger-briefing.wav",
    model=<grok audio model>,
    voice="Kore",
    format="audio/wav",
    instruct="Read in a calm, professional briefing tone.",
)

print(output_path)

Transcription¶

The Transcription class transcribes local audio files.

Transcribe an audio file¶

from grok import Transcription

transcription = Transcription()

text = transcription.transcribe(
    path="samples/audio/meeting.wav",
    model=<grok audio model>,
    language="English",
    mime_type="audio/wav",
    temperature=0.2,
)

print(text)

Transcribe a specific time range¶

from grok import Transcription

transcription = Transcription()

text = transcription.transcribe(
    path="samples/audio/meeting.wav",
    model=<grok audio model>,
    language="English",
    mime_type="audio/wav",
    start_time=30.0,
    end_time=90.0,
)

print(text)

Translation¶

The Translation class translates spoken audio into a target language.

Translate audio to English¶

from grok import Translation

translation = Translation()

translated_text = translation.translate(
    path="samples/audio/spanish-briefing.wav",
    model=<grok audio model>",
    language="English",
    source="Spanish",
    mime_type="audio/wav",
)

print(translated_text)

Translate a selected time range¶

from grok import Translation

translation = Translation()

translated_text = translation.translate(
    path="samples/audio/french-briefing.wav",
    model=<grok audio model>,
    language="English",
    source="French",
    mime_type="audio/wav",
    start_time=10.0,
    end_time=60.0,
)

print(translated_text)

Files¶

The Files class supports XAI file upload, file retrieval, file listing, document summarization, document search, and file-backed workflows.

Upload a file¶

from grok import Files

files = Files()

uploaded_file = files.upload(
    filepath="samples/documents/policy.pdf",
    name="Policy Reference",
)

print(uploaded_file)

Retrieve a file¶

from grok import Files

files = Files()

file_metadata = files.retrieve(
    file_id="files/example-file-id"
)

print(file_metadata)

Summarize a document¶

from grok import Files

files = Files()

summary = files.summarize(
    prompt=(
        "Summarize this document for an executive audience. Include purpose, key requirements, "
        "deadlines, risks, and recommended follow-up actions."
    ),
    filepath="samples/documents/policy.pdf",
    model=<grok model>,
    temperature=0.2,
    max_tokens=1500,
)

print(summary)

Search a document¶

from grok import Files

files = Files()

answer = files.search(
    prompt="Find every section that discusses auditability, internal controls, or reporting requirements.",
    filepath="samples/documents/policy.pdf",
    model=<grok model>
    temperature=0.2,
    max_tokens=1500,
)

print(answer)

List configured cloud-backed files¶

from grok import Files

files = Files()

available_files = files.list()

for file_name in available_files:
    print(file_name)

FileSearch¶

The FileSearch class manages grok File Search Store resources.

List file-search stores¶

from grok import FileSearch

stores = FileSearch()

available_stores = stores.list()

for store in available_stores:
    print(store)

Create a file-search store¶

from grok import FileSearch

stores = FileSearch()

store = stores.create(
    name="Budget Execution Reference Library"
)

print(store)

Retrieve a file-search store¶

from grok import FileSearch

stores = FileSearch()

store = stores.retrieve(
    store_id="fileSearchStores/example-store-id"
)

print(store)

Delete a file-search store¶

from grok import FileSearch

stores = FileSearch()

deleted = stores.delete(
    store_id="fileSearchStores/example-store-id",
    force=True,
)

print(deleted)

End-to-End Example: Document Summary to Executive Brief¶

This example uploads a document, summarizes it, and then uses the Chat wrapper to produce a polished executive briefing.

from grok import Files, Chat

files = Files()
chat = Chat()

summary = files.summarize(
    prompt=(
        "Summarize this document. Focus on purpose, requirements, deadlines, risks, "
        "and recommended actions."
    ),
    filepath="samples/documents/policy.pdf",
    model=<grok model>,
    temperature=0.2,
    max_tokens=1500,
)

briefing = chat.generate_text(
    prompt=(
        "Convert the following document summary into an executive briefing with "
        "Background, Key Findings, Risks, and Recommended Actions sections.\n\n"
        f"{summary}"
    ),
    model=<grok model>,
    temperature=0.2,
    max_tokens=1500,
)

print(briefing)

End-to-End Example: Architecture Image Analysis¶

This example analyzes the Donger architecture image stored in the documentation assets folder.

from grok import Images

images = Images()

analysis = images.analyze(
    prompt=(
        "Review this architecture image for technical documentation. Identify whether the "
        "main layers, service boundaries, request flow, configuration flow, and persistence "
        "flow are clear."
    ),
    path="docs/images/Donger-architecture.png",
    model=<grok model>,
    response_modalities="text",
)

print(analysis)

Usage Examples¶

The examples below show common Donger workflows by mode and by the wrapper class that supports each workflow. They are written from the user-interface perspective first, with the corresponding implementation class noted where it helps connect the application behavior to the API documentation.

Text Mode¶

Backing class: grok.Chat

Use Text mode when you want a grok-backed response to a prompt, with optional system instructions, model settings, grounding tools, URL context, or file-search support.

Example: Generate a budget-analysis summary¶

Select Text mode from the sidebar.
Select a supported grok text model.
Enter system instructions such as:

You are a federal budget analyst. Answer with concise, source-aware analysis.

Enter a prompt such as:

Summarize the major budget-execution risks associated with delayed apportionment,
continuing resolutions, and late-year obligation pressure.

Adjust generation settings if needed:
- lower temperature for formal analysis;
- higher maximum tokens for longer explanations;
- Google Search grounding when current external context is required.
Submit the prompt and review the generated response.

Example: Ask a grounded question with URL context¶

Select Text mode.
Enable URL-context support if the selected model supports it.
Add one or more reference URLs in the URL input area.
Ask a focused question, for example:

Based on the provided references, identify the key compliance requirements and
summarize them as an implementation checklist.

Review the answer and any returned grounding metadata.

Images Mode¶

Backing class: grok.Images

Use Images mode for image generation, image analysis, and image editing workflows.

Example: Generate an architecture graphic¶

Select Images mode.
Open the Generate tab.
Select an image-capable grok model.
Enter a detailed prompt, for example:

Create a dark-themed technical architecture diagram for a Streamlit application
that uses grok class, local SQLite persistence, document retrieval, and
XAI Cloud integrations.

Choose an aspect ratio such as 16:9.
Choose an output MIME type such as image/png.
Submit the request.
Save the generated image into docs/images/ if it will be used in the documentation.

Example: Analyze an uploaded screenshot¶

Select Images mode.
Open the Analyze tab.
Upload an image or screenshot.
Enter a prompt such as:

Review this screenshot for layout issues, missing labels, visual hierarchy problems,
and documentation-readiness.

Submit the analysis request.
Use the response to refine the UI, README, or documentation page.

Example: Edit an uploaded image¶

Select Images mode.
Open the Edit tab.
Upload the source image.
Enter edit instructions such as:

Make the diagram wider, improve text contrast, preserve the dark theme, and make
the architecture layers easier to distinguish.

Submit the request.
Review the returned edited image before replacing any documentation asset.

Audio Mode¶

Audio mode supports transcription, translation, and text-to-speech. These workflows are implemented through the grok.Transcription, grok.Translation, and grok.TTS classes.

Example: Transcribe an uploaded audio file¶

Backing class: grok.Transcription

Select Audio mode.
Choose the Transcribe workflow.
Upload a supported audio file, such as WAV, MP3, AIFF, AAC, OGG, or FLAC.
Select the expected language or leave it on automatic detection.
Optionally provide a start time and end time to transcribe only part of the file.
Submit the transcription request.
Review the returned transcript and copy it into notes, documentation, or downstream analysis.

Example: Translate spoken audio¶

Backing class: grok.Translation

Select Audio mode.
Choose the Translate workflow.
Upload the audio file.
Select the target language.
Optionally identify the source language.
Submit the translation request.
Review the translated text output.

Example: Generate spoken audio from text¶

Backing class: grok.TTS

Select Audio mode.
Choose the Text-to-Speech workflow.
Enter the text to convert into speech.
Select a TTS-capable model.
Select a voice.
Optionally adjust speaking style through instructions, such as:

Read this in a calm, professional briefing tone.

Generate the audio.
Play or download the generated WAV output.

Embedding Mode¶

Backing class: grok.Embeddings

Use Embedding mode to convert text into vector representations for semantic comparison, retrieval, clustering, classification, or document Q&A support.

Example: Create an embedding for semantic search¶

Select Embedding mode.
Choose an embedding model.
Paste source text, for example:

The Working Capital Fund supports shared services, technology modernization,
and reimbursable service delivery across participating offices.

Select the task type when appropriate, such as:
- RETRIEVAL_DOCUMENT for indexed source material;
- RETRIEVAL_QUERY for search questions;
- SEMANTIC_SIMILARITY for comparison workflows.
Configure dimensions if the model supports dimensionality controls.
Generate the embedding.
Review the vector output and any text metrics shown in the interface.

Example: Embed multiple chunks¶

Select Embedding mode.
Paste multiple paragraphs or chunked text.
Configure chunk size and overlap where available.
Generate embeddings.
Use the output for retrieval, similarity scoring, or local vector storage.

Document Q&A Mode¶

Backing classes: grok.Files, grok.Embeddings, and local retrieval helpers

Use Document Q&A mode when you want Donger to answer questions using uploaded documents as context.

Example: Ask a question against a PDF¶

Select Document Q&A mode.
Upload one or more PDF files.
Preview the extracted text when available.
Build or rebuild the retrieval index.
Ask a document-grounded question, for example:

What are the main reporting requirements in this document, and what offices are
responsible for each requirement?

Review the answer and supporting context.
Refine the question if the answer needs more precision.

Example: Compare requirements across uploaded documents¶

Upload multiple policy, budget, or technical documents.
Build the retrieval index.
Ask:

Compare the requirements across these documents and identify overlapping,
conflicting, or missing implementation steps.

Review the response for document-grounded similarities and differences.

Files Mode¶

Backing class: grok.Files

Use Files mode for grok file upload, file metadata, document summarization, document search, and file-backed prompt workflows.

Example: Upload a file for later use¶

Select Files mode.
Choose the upload workflow.
Select a local file.
Provide a display name when required.
Upload the file.
Record the returned file metadata or file identifier if it will be reused in another workflow.

Example: Summarize an uploaded document¶

Select Files mode.
Upload or select a document.
Enter a summary prompt such as:

Summarize this document for a senior executive. Focus on purpose, major decisions,
risks, deadlines, and required follow-up actions.

Submit the request.
Review the generated summary.

Example: Search within an uploaded file¶

Select Files mode.
Upload or select the document to search.
Enter a targeted question, for example:

Find every section that discusses auditability, internal controls, or reporting
requirements.

Submit the search request.
Review the response and supporting references.

File Search Stores Mode¶

Backing class: grok.FileSearch

Use File Search Stores mode to create, retrieve, list, delete, and manage grok file-search stores.

Example: Create a file-search store¶

Select File Search Stores mode.
Choose the create-store workflow.
Enter a display name, such as:

Budget Execution Reference Library

Create the store.
Confirm that the new store appears in the available store list.

Example: Retrieve a file-search store¶

Select File Search Stores mode.
Choose a store from the available collection list.
Retrieve the store metadata.
Confirm the display name, resource name, and available status information.

Example: Delete a file-search store¶

Select File Search Stores mode.
Select the store to delete.
Confirm that the selected store is not needed by an active workflow.
Delete the store.
Refresh the store list.

Google Cloud Buckets Mode¶

Backing class: grok.CloudBuckets

Use Google Cloud Buckets mode when Donger needs to interact with Google Cloud Storage buckets and objects.

Example: Upload a document to a bucket¶

Select Google Cloud Buckets mode.
Choose the upload workflow.
Select a local file.
Enter the target bucket name.
Enter an object name or accept the default object name derived from the file path.
Upload the file.
Confirm that the object appears in the bucket listing.

Example: Retrieve a bucket object¶

Select Google Cloud Buckets mode.
Enter the bucket name.
Enter the object name.
Retrieve the object metadata.
Use the returned information to confirm that the expected cloud object is available.

Example: List bucket contents¶

Select Google Cloud Buckets mode.
Enter the bucket name.
Run the list workflow.
Review the returned object names and identifiers.
Use the results to select files for downstream document, data, or retrieval workflows.

Prompt Engineering Mode¶

Prompt Engineering mode manages reusable prompts stored in the local SQLite Prompts table.

Example: Create a reusable system instruction¶

Select Prompt Engineering mode.
Create a new prompt record.
Enter a name such as:

Federal Budget Analyst

Enter reusable instruction text, such as:

You are a federal budget analyst. Use precise budget terminology, distinguish
budget authority from obligations and outlays, and present conclusions in a
concise executive format.

Save the prompt record.
Reuse the prompt in Text, Document Q&A, or file-backed workflows.

Example: Update an existing prompt¶

Select Prompt Engineering mode.
Search or browse existing prompt records.
Select the prompt to edit.
Update the name, caption, text, version, or identifier.
Save the updated record.
Confirm that the revised prompt appears in the prompt list.

Data Management Mode¶

Data Management mode supports SQLite-backed data import, browsing, filtering, aggregation, visualization, administration, and guarded SQL queries.

Example: Import a CSV file¶

Select Data Management mode.
Open the Import tab.
Upload a CSV file.
Confirm the inferred table name and column structure.
Import the data into SQLite.
Open the Browse or Explore tab to confirm the imported rows.

Example: Filter and aggregate imported data¶

Select Data Management mode.
Open the Filter tab.
Choose the imported table.
Apply one or more column filters.
Open the Aggregate tab.
Select grouping columns and numeric measures.
Run the aggregation.
Review the summarized output.

Example: Run a guarded read-only SQL query¶

Select Data Management mode.
Open the SQL tab.
Enter a read-only query, such as:

SELECT
    AccountName,
    SUM(BY) AS BudgetYearAmount
FROM CombinedSchedules
GROUP BY AccountName
ORDER BY BudgetYearAmount DESC;

Run the query.
Review the result table.
Avoid destructive SQL operations in user-facing workflows.

Data Export Mode¶

Data Export mode supports exporting local data assets, prompt records, generated artifacts, or application-managed datasets where configured.

Example: Export prompt records¶

Select Data Export mode.
Choose the prompt-record export workflow.
Select the desired output format.
Generate the export.
Save the exported file for backup, migration, or documentation review.

Example: Export imported data¶

Select Data Export mode.
Choose the table or dataset to export.
Select the output format.
Generate the export.
Confirm that the exported file contains the expected rows and columns.

Common End-to-End Workflow¶

The following workflow combines several Donger modes:

Use Files mode to upload a policy or budget document.
Use Document Q&A mode to ask targeted questions against the uploaded document.
Use Embedding mode to inspect or generate vectors for semantic retrieval.
Use Prompt Engineering mode to save a reusable analytical instruction.
Use Text mode to generate a final executive summary.
Use Data Export mode to export reusable records or supporting data.

This pattern is useful when turning source documents into structured analysis, reusable prompts, documentation content, or decision-support outputs.