donger-py 0.1.0

Donger

Core Capabilities • Model Integration • Configuration • Installation • Features • Architecture • Runtime • License

PyPI application

python -m pip install donger-py
donger

donger opens the tabless Windows WebView2 window by default. donger-browser opens standard browser mode, including on other platforms. Python 3.11–3.12 is required. Windows requires Edge WebView2 Runtime. The distribution is donger-py; the import is donger. See installation and PyPI publishing.

Donger is a xAI Grok-powered, multimodal application written in Python for data, financial and policy analysis. It combines conversational ai and structured text generation, image and audio workflows, document-grounded question answering, file analysis and Collection management, prompt engineering, and SQLite-based data administration in one analyst-oriented interface. Food is not included.

🎥 Demo

☁️ Cloud

Core Capabilities

Model Integration

xAI Grok

Donger routes provider-backed functionality through the local grok class. The interface discovers wrapper capabilities at runtime and exposes only modes backed by an available Grok class. The configured model families include Grok reasoning/text models and Grok image-generation and image-editing models.

Depending on the selected model and wrapper capability, Donger supports:

• Multi-turn chat and text generation.
• Configurable temperature, top-p, penalties, token limits, stop sequences, storage, streaming, and reasoning controls.
• Web search and xAI Collections search for grounded responses.
• Plain text, JSON object, and JSON Schema response formats.
• Image generation, image editing, and multimodal analysis.
• Audio generation and speech-processing workflows.
• File lifecycle and Collection document management.

Domain Knowledge Collections

Donger is configured to work with xAI Collections covering federal financial regulations, public laws, explanatory statements, governance material, DoD data and regulations, Army field manuals, Army techniques publications, and Army style guides. Collection identifiers remain configuration data and should be replaced with identifiers available to the deployed xAI account.

Hugging Face Datasets

The project references curated datasets covering federal budget execution, appropriations and fiscal law, accounting and audit standards, and DoD policy documentation. These repositories are knowledge sources for retrieval and evaluation; this application does not load a Hugging Face fine-tuned model directly in the current source.

🔑 Configuration

Obtain xAI credentials using the project’s [Grok API setup instructions](https://docs.x.ai/overview, then configure the environment as described in the environment setup guide.

The standard xAI API base URL is configured as https://api.x.ai/v1. API keys may also be entered at runtime through the Streamlit sidebar. Treat credentials as secrets and do not commit them to source control.

📦 Installation

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
streamlit run app.py

For Command Prompt, activate the environment with .venv\Scripts\activate.bat. On Linux or macOS, use source .venv/bin/activate.

The repository must also contain the project-local grok wrapper and boogr package imported by app.py, together with the configured resources/, stores/, and logging/ directories.

Application Features

1. Chat and Text Generation

• Chat mode provides a focused Grok conversation with retained session messages.
• Text mode provides detailed model, inference, grounding, response, and instruction controls.
• Prompt templates can be filtered by category and loaded into the active instruction editor.
• Responses can include extracted text, sources, structured content, and downloadable artifacts.

2. Grounding and Source Attribution

• Web search can be constrained by allowed domains.
• Collections search grounds responses in selected xAI knowledge collections.
• Response parsing extracts source titles, URLs, snippets, file citations, and Collection metadata when returned by the provider.
• Source-aware output supports review and auditability; it does not replace source validation.

3. Images and Audio

• Image workflows support provider-advertised generation, editing, variation, and analysis options.
• Uploaded images can be supplied to multimodal Grok models with configurable detail levels.
• Audio workflows support provider-advertised speech synthesis, transcription, translation, and analysis operations.
• Generated or transformed media can be previewed and downloaded from the application.

4. Document Q&A

• Accepts PDF, text, Markdown, Word, JSON, CSV, and Excel documents.
• Extracts text, applies configurable cleaning, and segments content by sentences with a token-window fallback.
• Builds local semantic context with sentence-transformer embeddings and similarity ranking.
• Sends selected context and the user’s question to Grok for a grounded answer.
• Maintains separate instructions, document state, messages, answers, and source output.

5. Embeddings

• Accepts direct text, uploaded content, processed text, or chunked input.
• Generates embeddings through the Grok embeddings wrapper when available.
• Displays vector dimensions, record counts, previews, and output tables.
• Supports CSV export and local SQLite persistence for downstream semantic search.

6. Files and Collections

• Files mode manages xAI-hosted assets through upload, list, retrieve, content, download, and delete operations exposed by the wrapper.
• Collections mode creates, lists, selects, updates, and deletes Collections.
• Documents can be uploaded and attached to a Collection, listed, inspected, and removed.
• Selected Collections can ground an interactive conversation through Collections Search.

7. Prompt Engineering

• Stores prompt name, category, content, version, variables, description, and timestamps in SQLite.
• Provides search, sorting, pagination, record selection, and an authoritative editor.
• Supports create, update, delete, clear, load, and XML/Markdown instruction conversion workflows.

8. Data Management

• Uses a local SQLite database at stores/sqlite/Data.db by default.
• Imports structured data, profiles tables, filters rows, aggregates values, and renders Plotly visualizations.
• Exports query and table results and supports index, table, column, and schema administration.
• Provides a guarded SQL console that blocks multiple statements and destructive keywords.

Data Storage & Architecture

Local prompt and data records persist in SQLite. Streamlit interaction state is session-scoped. xAI-hosted files and Collections persist according to the xAI account and API lifecycle.

Intended Users

• Federal budget and financial-management analysts.
• DoD and civilian-agency policy professionals.
• Program, portfolio, audit, and compliance analysts.
• Data scientists supporting formulation, execution, reporting, and semantic retrieval.
• Managers requiring traceable analytical assistance across authoritative guidance.

Federal Budget Guidance

• Financial guidance common across federal agencies.

• 

Department of War Guidance

• Support for DoD-specific budget formulation, execution, audit, and compliance analysis.\

• 

File A (Account Balances)

• File A is part of the package of data submitted to USAspending.gov every month by federal agencies, as required by the DATA Act. As part of the monthly submission process, agencies generate File A automatically from data in the Governmentwide Treasury Account Symbol Adjusted Trial Balance System (GTAS), or choose to upload their own custom File A data.

• File A contains budgetary resources, obligation, and outlay data for all the relevant Treasury Account Symbols (TAS) in a reporting agency, with additional breakdown by Budget Function. It includes both award and non-award spending (grouped together), and crosswalks with the SF 133 report.

SF 133

• The SF 133 Report on Budget Execution and Budgetary Resources fulfills the requirement in 31 U.S.C. 1511 - 1514 that the President review Federal expenditures at least four times a year.

• SF 133s provide historical reference that can be used to help prepare the President's Budget, program operating plans, and spend-out rate estimates.

• Agencies submit the data that appear on these reports to the Department of the Treasury Bureau of Fiscal Service. While OMB publishes these reports as a service to agency budget and finance offices and other interested parties, the underlying data is submitted by the agencies.

🖥 Core Runtime Requirements

Install the exact versions pinned by the repository’s requirements.txt. Provider model names and capabilities can change independently of Donger; use models returned by the installed Grok wrapper and enabled for the configured xAI account.

Project Structure

Donger/
├── app.py                  # Streamlit application and mode implementations
├── config.py               # Application constants, models, modes, paths, and help text
├── models.py               # Shared application data/configuration models
├── grok.py                 # Project-local xAI wrapper
├── requirements.txt        # Python dependencies
├── .streamlit/
│   └── config.toml         # Streamlit theme and runtime configuration
├── resources/              # Branding, images, avatars, setup guidance, and static assets
├── stores/
│   └── sqlite/
│       └── Data.db         # Default local application database
└── logging/                # Local exception-log storage

The actual repository may contain additional modules and documentation. Preserve the relative paths configured in config.py when relocating application assets.

Operational Considerations

• Validate model-generated conclusions against authoritative laws, regulations, policy documents, source systems, and responsible officials.
• Review retrieved citations and Collection results before relying on them in an official product.
• Do not upload classified, controlled, privileged, procurement-sensitive, personally identifiable, or otherwise restricted information unless the deployed environment and xAI account are formally authorized for that data.
• Protect API and management keys through environment variables or an approved secret store.
• Back up stores/sqlite/Data.db before schema changes or destructive administrative operations.
• Treat the built-in SQL safeguards as a user-interface control, not as a substitute for database permissions, backups, or deployment security.

Disclaimer

Donger is an analytical support tool and is not an authoritative source of federal law, policy, accounting treatment, budget authority, or legal advice. Outputs generated by large language models and retrieved content should be independently reviewed and validated by qualified personnel before use in official decisions, submissions, reports, or policy actions.

📝 License

Donger is distributed under the MIT License.