Metadata-Version: 2.4
Name: buddy-py
Version: 0.1.0
Summary: Financial management Streamlit assistant with provider chat, retrieval, and document analysis
Author: Terry Eppler
License-Expression: MIT
Project-URL: Homepage, https://github.com/is-leeroy-jenkins/buddy
Project-URL: Documentation, https://is-leeroy-jenkins.github.io/buddy/
Project-URL: Issues, https://github.com/is-leeroy-jenkins/buddy/issues
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: google-genai
Requires-Dist: google-cloud-storage
Requires-Dist: numpy==1.26.4
Requires-Dist: matplotlib
Requires-Dist: openpyxl
Requires-Dist: openai
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: typing_extensions<5,>=4.11
Requires-Dist: pymupdf
Requires-Dist: httpx>=0.28.1
Requires-Dist: reportlab>=4.0.8
Requires-Dist: streamlit
Requires-Dist: streamlit-extras
Requires-Dist: streamlit-pdf
Requires-Dist: pandas
Requires-Dist: python-dotenv
Requires-Dist: python-docx
Requires-Dist: tabulate>=0.9.0
Requires-Dist: sentence-transformers==2.7.0
Requires-Dist: transformers==4.41.2
Requires-Dist: huggingface_hub==0.23.5
Requires-Dist: safetensors==0.4.3
Requires-Dist: tiktoken
Requires-Dist: plotly==6.3.0
Requires-Dist: xai-sdk
Requires-Dist: pillow>=10.0.0
Requires-Dist: requests==2.32.4
Requires-Dist: torch==2.4.1
Requires-Dist: torchvision==0.19.1
Requires-Dist: scikit-learn==1.5.1
Requires-Dist: scipy==1.13.1
Requires-Dist: regex==2024.5.15
Requires-Dist: sentencepiece==0.2.0
Requires-Dist: tqdm==4.66.4
Requires-Dist: filelock==3.15.4
Requires-Dist: fsspec==2024.6.1
Requires-Dist: packaging<26,>=25
Requires-Dist: pyyaml==6.0.1
Requires-Dist: sqlite-vec>=0.1
Requires-Dist: pywebview>=5.0; sys_platform == "win32"
Dynamic: license-file

###### Buddy

![](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/Buddy_Project.png)

<p align="center">
  <a href="#-demo">Demo</a>
  &bull;
  <a href="#core-capabilities">Core Capabilities</a>
  &bull;
  <a href="#model-integration">LLM Integration</a>
  &bull;
  <a href="#-required-api-keys">API Keys</a>
  &bull;
  <a href="resources/installation.md">Installation</a>
  &bull;
  <a href="#application-features">Features</a>
  &bull;
  <a href="#data-storage--architecture">Architecture</a>
  &bull;
  <a href="#-core-runtime-requirements">Runtime</a>
  &bull;
  <a href="#-license">License</a>
</p>

___


[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-0078FC?style=for-the-badge&logo=github)](https://is-leeroy-jenkins.github.io/buddy/)

## PyPI application

```powershell
python -m pip install buddy-py
buddy
```

`buddy` opens the tabless Windows WebView2 window by default. Standard browser
mode uses `buddy-browser`. Python 3.11 or 3.12 is recommended for the pinned
scientific dependencies. Windows requires Edge WebView2 Runtime.
The distribution is `buddy-py`; the import is `buddy`. Use a separate virtual
environment from the unrelated PyPI `buddy` distribution.
See [installation](resources/installation.md) and
[PyPI publishing](resources/pypi-release.md).

Budget Buddy is an federal financial management AI tool designed to support fderal budget/financial
analysts, managers, and policy professionals. It integrates large language models (LLMs) such as
OpenAI's ChatGPT 5+, xAI's Grok 3/4, and Googles Gemini 3/4 for retrieval-augmented generation (
RAG),
semantic searching, and structured prompt engineering to assist with interpretation of financial
guidance,
budget execution data, and a vectorized data set of financial policy documents. Buddy is integrated
with **GPT-5.2**, **Grok**, **Gemini**, and has been **fine-tuned** on datasets
on vectorized financial management and policy datasets hosted on Huggingface:

## 🎥 Demo


![](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/buddy-demo.gif)

___

![](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/buddy-demo.gif)



## ☁️ Cloud

<table>
<tr>
<td align="center">
<img width="190" height="1" alt=""><br>
<a href="https://buddy.thankfulocean-66471d87.eastus.azurecontainerapps.io">
<img src="https://img.shields.io/badge/Docker-App-2496ED?logo=docker&logoColor=white" alt="Docker App">
</a>
</td>

<td align="center">
<img width="190" height="1" alt=""><br>
<a href="https://buddy-py.streamlit.app/">
<img src="https://img.shields.io/badge/Streamlit-App-FF4B4B?logo=streamlit&logoColor=white" alt="Streamlit App">
</a>
</td>

<td align="center">
<img width="190" height="1" alt=""><br>
<a href="https://chatgpt.com/g/g-67579c62ebf88191b67889476229e498-buddy">
<img src="https://img.shields.io/badge/OpenAI-ChatGPT-412991?logo=openai&logoColor=white" alt="OpenAI GPT">
</a>
</td>

<td align="center">
<img width="190" height="1" alt=""><br>
<a href="https://dbc-a0c21f80-7bb3.cloud.databricks.com/browse/folders/3169291152438532?o=7474645703081351">
<img src="https://img.shields.io/badge/Databricks%20Repo-Buddy--Py-FF3621?logo=databricks&logoColor=white" alt="Databricks Notebook">
</a>
</td>

<td align="center">
<a href="https://leeroy.usw-16.palantirfoundry.com/shares/links/mwmui22wwb7so">
<img width="190" height="1" alt=""><br>
<img src="https://img.shields.io/badge/Palantir%20Foundry-Repo-101113?logo=palantir&logoColor=white" alt="Palantir Repo">
</a>
</td>
</tr>
</table>
## Core Capabilities

| Mode | Description |
  | ----------------------- | ---------------------------------------------------------------- |
| 📝 **Text Generation**  | Structured LLM interaction with full parameter control |
| 🖼 **Image Generation** | Prompt-based image synthesis with provider configuration |
| 🔊 **Audio Processing** | Text-to-Speech and Speech-to-Text workflows |
| 📚 **Document Q&A**     | Context-aware querying of uploaded or embedded documents |
| 🧬 **Embeddings**       | Vector creation and similarity-based search |
| 🗄 **Vector Stores**    | Persistent semantic storage (SQLite / Chroma / others)           |
| 🧾 **Data Management**  | Schema inspection, profiling, import/export, and transformations |
| 🛠 **Utilities**        | Runtime configuration, environment inspection, reset tools |


## Model Integration

### GPT-5.2 (Primary Inference Engine)

Budget Buddy uses **GPT-5.2** via the OpenAI Responses API as its primary inference engine. The
application is structured to support:

* Structured response outputs (text, sources, analytical artifacts)
* Tool-generated analysis (tables, derived files)
* Prompt versioning via OpenAI Prompt IDs

### Fine-Tuned Models on Hugging Face

[![HuggingFace](https://huggingface.co/datasets/huggingface/badges/resolve/main/model-on-hf-sm.svg)](https://huggingface.co/leeroy-jankins/models)

In addition to base GPT-5.2 capabilities, Budget Buddy is designed to leverage **fine-tuned large
language models hosted on Hugging Face**, trained on:

* Federal budget execution data
* Appropriations and fiscal law guidance
* DoD-specific and government-wide policy documentation
* Structured tabular datasets used in budget reporting and analysis

These fine-tuned models improve:

* Domain-specific accuracy
* Terminology alignment (OMB, DoD, Treasury, GAO)
* Consistency when answering budget and execution questions

## 🔑 Required API Keys

- Buddy’s capabilities are provided by OpenAI, Grok, and Gemini with instructions for each below.
- Each provider provides language models, embedding models, image generators, or audio systems
- Buddy gives users flexibility the ability to improve accuracy by comparing output across model
  ecosystems.

#### Instructions

- [OpenAI API Key](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/setup/openai.md)
- [Grok API Key](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/setup/xai.md)
- [Gemini API Key](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/setup/gemini.md)

## 🔐 Environment Variables

- After obtaining the api keys, set environment variables following instructions
  found [here](https://github.com/is-leeroy-jenkins/Buddy/blob/main/resources/setup/environments.md)

| Variable          | Required For |
| ----------------- | ------------ |
| OPENAI_API_KEY    | OpenAI       |
| GOOGLE_API_KEY    | Gemini       |
| GROK_API_KEY      | Grok         |

## 📦 Installation
```python
    python -m venv .venv
    .venv\Scripts\activate  # Windows
    python -m pip install - r requirements.txt
    streamlit run app.py
```

## Application Features

### 1. Conversational Chat Interface

* Analyst-oriented natural language interaction
* Execution modes:

    * **Standard**
    * **Guidance Only**
    * **Analysis Only**
* Custom chat avatars and branding support
* Session-scoped conversational context

### 2. Source Attribution & Guidance Review

* Automatic extraction of source references
* Display of document titles, snippets, and links
* Supports auditability and defensible analysis

### 3. Analytical Artifacts

* Tables and text generated by model-driven analysis
* Downloadable files produced during reasoning
* Dedicated Analysis tab for structured outputs

### 4. Prompt & System Instruction Management

* SQLite-backed prompt repository
* Create, edit, load, and version system instructions
* Convert between:

    * XML-delimited instruction blocks
    * Markdown representations

This enables controlled experimentation and governance of AI behavior.

### 5. Retrieval-Augmented Generation (RAG)

* Upload reference documents
* Chunk and inject relevant context into prompts
* Ground responses in authoritative material rather than model priors alone

### 6. Semantic Search

* Sentence-level embeddings
* SQLite-backed vector storage
* Cosine similarity scoring
* Reusable embedded corpora across sessions

### 7. Export & Reporting

* Export system instructions as XML or Markdown
* Export chat history as Markdown or PDF
* Designed for briefings, documentation, and archival use

## Data Storage & Architecture

* Local SQLite database for:

    * Prompt storage
    * Semantic embeddings
    * (Planned) chat history persistence
    * Modular design anticipates:
    * External vector databases
    * Centralized prompt registries
    * Multi-user or shared analytical environments

## Intended Users

* Federal budget analysts
* Financial management professionals
* DoD and civilian agency policy analysts
* Data scientists supporting budget formulation and execution
* Program and portfolio analysts requiring explainable AI assistance

## Federal Budget Guidance

- Financial guidance common across federal agencies.

- [![HuggingFace](https://huggingface.co/datasets/huggingface/badges/resolve/main/model-on-hf-sm.svg)](https://huggingface.co/leeroy-jankins/datasets)

| File Name                                                                                                                                                                 | Description                                                                                                            |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| [Balanced Budget and Emergency Deficit Control Act of 1985](https://huggingface.co/datasets/leeroy-jankins/The-Balanced-Budget-And-Emergency-Deficit-Control-Act-of-1985) | Establishes statutory limits on federal spending and deficit control mechanisms, including sequestration procedures.   |
| [Budget Control Act of 2011](https://huggingface.co/datasets/leeroy-jankins/The-Budget-Control-Act-2011)                                                                  | Sets discretionary spending caps and establishes enforcement mechanisms to control federal deficits.                   |
| [Digital Accountability And Transparency Act of 2014](https://huggingface.co/datasets/leeroy-jankins/Data-Act-2014)                                                       | Requires standardized federal spending data and improved transparency through government-wide financial reporting.     |
| [Federal Account Symbols And Titles Book](https://huggingface.co/datasets/leeroy-jankins/FastBook)                                                                        | Defines Treasury account symbols and official titles used for federal budgetary and accounting purposes.               |
| [Federal Acquisition Regulation](https://huggingface.co/datasets/leeroy-jankins/Federal-Acquisition-Regulation)                                                           | Establishes uniform policies and procedures governing the acquisition of goods and services by federal agencies.       |
| [Federal Government Standards For Internal Controls](https://huggingface.co/datasets/leeroy-jankins/Federal-Government-Standards-For-Internal-Controls)                   | Defines the internal control framework for federal agencies to ensure accountability, integrity, and compliance.       |
| [Federal Managers Financial Integrity Act of 1982](https://huggingface.co/datasets/leeroy-jankins/FMFIA-1982)                                                             | Requires agencies to establish internal controls and report annually on their effectiveness.                           |
| [Federal Trust Fund Accounting Guide](https://huggingface.co/datasets/leeroy-jankins/Federal-Trust-Fund-Accounting-Guide)                                                 | Provides accounting guidance for the management and reporting of federal trust funds.                                  |
| [Financial Management Regulations DOD 7000-14-R](https://huggingface.co/datasets/leeroy-jankins/DOD-7000-14-Financial-Management-Regulation)                                                                                                                        | Establishes DoD-specific financial management policies, procedures, and accounting requirements.                       |
| [Fiscal Responsibility Act](https://huggingface.co/datasets/leeroy-jankins/The-Fiscal-Responsibility-Act-of-2023)                                                                                                                                                 | Establishes statutory measures intended to improve fiscal discipline and control federal spending.                     |
| [Government Auditing Standards](https://huggingface.co/datasets/leeroy-jankins/Government-Auditing-Standards)                                                                                                                                             | Sets professional standards for audits of government organizations, programs, activities, and functions.               |
| [Government Invoicing User Guide](https://huggingface.co/datasets/leeroy-jankins/Government-Performance-and-Results-Act)                                                                                                                                           | Provides guidance on federal invoicing standards and processes for government transactions.                            |
| [Government Performance and Results Act of 1993](https://huggingface.co/datasets/leeroy-jankins/Government-Performance-and-Results-Act)                                                                                                                            | Requires agencies to engage in strategic planning and performance measurement to improve program effectiveness.        |
| [GPRA Modernization Act of 2010](https://huggingface.co/datasets/leeroy-jankins/The-GPRA-Modernization-Act-Of-2010)                                                                                                                                            | Updates GPRA by strengthening performance management, cross-agency goals, and accountability.                          |
| [OMB Circular A-11 Preparation Submission And Execution Of The Budget](https://huggingface.co/datasets/leeroy-jankins/OMB-Circular-A-11)                                                                                                      | Provides comprehensive guidance for preparing, submitting, and executing the President’s Budget.                       |
| [OMB Circular A-11 Section 120 Apportionment Process](https://huggingface.co/datasets/leeroy-jankins/OMB-Circular-A11-Section-120-Apportionment-Process)                                                                                                                       | Defines the apportionment process used to control the rate of obligation of budgetary resources.                       |
| [OMB Circular A-123 Managements Responsibility for Enterprise Risk Management and Internal Control](https://huggingface.co/datasets/leeroy-jankins/OMB-Circular-A-123)                                                                         | Defines management responsibilities for internal control and enterprise risk management across federal agencies.       |
| [Federal Trust Fund Accounting Guide](https://huggingface.co/datasets/leeroy-jankins/Federal-Trust-Fund-Accounting-Guide)                                                                                                                       | Establishes requirements for federal agency financial statements and reporting.                                        |
| [Principles Of Federal Appropriations Law Volume One](https://huggingface.co/datasets/leeroy-jankins/Principles-Of-Federal-Appropriations-Law)                                                                                                                       | Authoritative GAO guidance on foundational principles governing the use of federal appropriations.                     |
| [Statements of Federal Federal Financial Accounting Concepts and Standards](https://huggingface.co/datasets/leeroy-jankins/Statements-Of-Federal-Financial-Accounting-Concepts-And-Standards)                                                                                                 | Establishes accounting concepts and standards for federal financial reporting.                                         |
| [The Anti-Deficiency Act PL 97-258](https://huggingface.co/datasets/leeroy-jankins/The-Anti-Deficiency-Act)                                                                                                                                         | Prohibits federal agencies from obligating or expending funds in excess of appropriations or before enactment.         |
| [The Anti-Deficiency Reform and Enforcement Act of 2018](https://huggingface.co/datasets/leeroy-jankins/The-Anti-Deficiency-Reform-And-Enforcement-Act-Of-2018)                                                                                                                    | Strengthens Anti-Deficiency Act enforcement and reporting requirements to improve fiscal accountability.               |
| [The Chief Financial Officers Act of 1990](https://huggingface.co/datasets/leeroy-jankins/The-Chief-Financial-Officers-Act-1990)                                                                                                                                  | Establishes agency Chief Financial Officers and modernizes federal financial management practices.                     |
| [The Congressional Budget and Impoundment Control Act of 1974](https://huggingface.co/datasets/leeroy-jankins/The-Congressional-Budget-And-Impoundment-Control-Act-Of-1974)                                                                                                              | Establishes the congressional budget process and restricts executive impoundment of appropriated funds.                |
| [Statutory Pay As You Go Act of 2010](https://huggingface.co/datasets/leeroy-jankins/Statutory-Pay-As-You-Go-Act-of-2010)                                                                                                                                                   | Authorizes interagency agreements for the provision of goods and services on a reimbursable basis.                     |
| [The Stafford Act](https://huggingface.co/datasets/leeroy-jankins/The-Stafford-Act)                                                                                                                                                          | Provides the statutory framework for federal disaster response and emergency assistance.                               |
| [Federal Trust Fund Accounting Guide](https://huggingface.co/datasets/leeroy-jankins/Federal-Trust-Fund-Accounting-Guide)                                                                                                                                  | Provides additional appropriations authority beyond regular annual funding acts.                                       |
| [Title 2 Code of Federal Regulations – Uniform Administrative Requirements, Cost Principles, and Audit](https://huggingface.co/datasets/leeroy-jankins/Title-2-CFR-Uniform-Administrative-Requirements-Cost-Principles-And-Audit)                                                                     | Establishes uniform administrative, cost, and audit requirements for federal financial assistance.                     |
| [Title 31 Code of Federal Regulations – Money and Finance](https://huggingface.co/datasets/leeroy-jankins/Title-31-CFR-Money-and-Finance)                                                                                                                  | Codifies Treasury and federal financial management regulations governing money and finance.                            |
| [US Standard General Ledger Account Definitions](https://huggingface.co/datasets/leeroy-jankins/US-Standard-General-Ledger-Accounts-And-Definitions)                                                                                                                            | Defines standardized account structures used for federal accounting and financial reporting.                           |

## Department of War Guidance

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

- [![HuggingFace](https://huggingface.co/datasets/huggingface/badges/resolve/main/model-on-hf-sm.svg)](https://huggingface.co/leeroy-jankins/datasets)

| File Name                                                          | Description                                                                                                                     |
|--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| Access Management For DOD Information Systems DOD 8520-04          | Establishes Department of Defense policy for identity, credential, and access management (ICAM) across DoD information systems. |
| Acquisition Management Of Contractor-Prepared Data DOD 5010-12     | Defines requirements for managing, retaining, and accessing data produced by contractors during DoD acquisitions.               |
| Acquisition Transformation Strategy                                | Outlines DoD-wide strategic objectives for modernizing acquisition processes, governance, and workforce practices.              |
| Administrative Instruction DODAM 28                                | Provides administrative procedures and internal management guidance under the DoD Administrative Management framework.          |
| Audit Manual DOD 7600-07                                           | Establishes audit policies, responsibilities, and procedures for DoD financial and performance audits.                          |
| Civilian Personnel Management System Payroll DOD 1400-25-v550      | Governs payroll administration within the DoD Civilian Personnel Management System (CPMS).                                      |
| Civilian Personnel Management System Performance DOD 1400-25-v430  | Defines performance management policies for DoD civilian employees, including evaluation and appraisal standards.               |
| Cybersecurity Reciprocity Playbook DOD 2024-01-02                  | Provides guidance for reciprocal acceptance of cybersecurity authorizations across DoD components to reduce duplication.        |
| DevSecOps Fundamentals v2.5                                        | Introduces core principles, practices, and terminology for implementing DevSecOps in DoD environments.                          |
| DevSecOps OSS Development                                          | Addresses the development and use of open-source software within DoD DevSecOps pipelines.                                       |
| DevSecOps Playbook DODCIO 2021-10-19                               | Official DoD CIO guidance for planning, implementing, and scaling DevSecOps capabilities.                                       |
| DevSecOps Reference Design AWS Managed Services DODCIO 2021-10-19  | Provides a reference architecture for deploying DevSecOps using AWS managed services in DoD contexts.                           |
| DNS IP Address Use And Approval DOD 8410                           | Establishes policy for allocation, registration, and approval of DNS names and IP address usage within DoD networks.            |
| DOD Cloud Reference Design Cloud GitHub Azure                      | Reference architecture describing DoD-approved cloud implementation patterns using Microsoft Azure.                             |
| DOD AI Strategy                                                    | Defines DoD objectives, priorities, and governance principles for artificial intelligence adoption.                             |
| Emergency Management Program DOD 6055-17                           | Establishes policy for preparedness, response, recovery, and mitigation of emergencies affecting DoD operations.                |
| Forms Management Program DOD 7750-08                               | Governs the lifecycle management of DoD forms, including standardization and control.                                           |
| Information Network Transport DOD 8010-01                          | Provides policy for managing DoD network transport infrastructure and communications pathways.                                  |
| Information Technology Standards DOD 8310-01                       | Establishes requirements for adopting and enforcing IT standards across the Department of Defense.                              |
| Infosec Program and Securing SCI DOD 5200-01p                      | Governs information security programs, including the protection of Sensitive Compartmented Information (SCI).                   |
| Management Of DOD IE DOD 8000-01                                   | Establishes governance for managing the DoD Information Enterprise (IE).                                                        |
| Multifactor Authentication DOD Networks                            | Defines requirements for implementing MFA across DoD network environments to strengthen access security.                        |
| National Defense Strategy 2026                                     | Sets strategic defense priorities, threats, and force-planning guidance for the Department of Defense.                          |
| Online Information Management And Electronic Messaging DOD 8170-01 | Establishes policy for managing official DoD online content and electronic communications.                                      |
| OPSEC Manual DOD 5205-02                                           | Provides policy and procedures for Operations Security to protect critical information from adversaries.                        |
| Personnel Identity Protection Program DOD 1000-25                  | Establishes policies for identity protection and credentialing of DoD personnel.                                                |
| PPBE Reform Activities FY2026                                      | Describes planned reforms to the Planning, Programming, Budgeting, and Execution (PPBE) process for FY2026.                     |
| Records Management Standards DTM 22-001                            | Establishes mandatory standards for managing, retaining, and disposing of DoD records.                                          |
| Use Of Non-Government Owned Mobile Devices.                        | Provides policy governing the use of personally owned mobile devices for official DoD activities.                               |

## File A (Account Balances)

- [File A](https://www.usaspending.gov/download_center/custom_account_data) is part of the package
  of data submitted
  to [USAspending.gov](https://www.usaspending.gov/download_center/custom_account_data) 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)](https://fiscal.treasury.gov/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](https://portal.max.gov/portal/document/SF133/Budget/FACTS%20II%20-%20SF%20133%20Report%20on%20Budget%20Execution%20and%20Budgetary%20Resources.html)
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

| Category                       | Component / Library | Minimum Version     | Required    | Purpose / Notes                        |
| ------------------------------ | ------------------- | ------------------- | ----------- | -------------------------------------- |
| **Core Runtime**               | Python              | 3.10                | Yes         | Application runtime (3.11 recommended) |
|                                | Streamlit           | Latest stable       | Yes         | UI framework                           |
|                                | pip                 | Latest              | Yes         | Package management                     |
|                                | virtualenv / venv   | Any                 | Recommended | Environment isolation                  |
| **AI Providers**               | openai              | Latest              | Optional    | OpenAI Text, Image, Audio, Embeddings  |
|                                | anthropic           | Latest              | Optional    | Claude models                          |
|                                | google-generativeai | Latest              | Optional    | Gemini models                          |
|                                | mistralai           | Latest              | Optional    | Mistral models                         |
|                                | groq / xai client   | Latest              | Optional    | Grok models                            |
|                                | requests            | Latest              | Yes         | API communication layer                |
| **Document Processing**        | pypdf (or PyPDF2)   | Latest              | Yes         | PDF text extraction                    |
|                                | python-docx         | Latest              | Yes         | Word document parsing                  |
|                                | chardet             | Latest              | Optional    | Encoding detection                     |
|                                | base64 / io         | Built-in            | Yes         | Byte handling                          |
| **Embeddings & Vector Stores** | numpy               | Latest              | Yes         | Vector math                            |
|                                | pandas              | Latest              | Yes         | Data handling                          |
|                                | sqlite3             | Built-in            | Yes         | Local vector persistence               |
|                                | chromadb            | Latest              | Optional    | Persistent vector store                |
|                                | scikit-learn        | Latest              | Optional    | Similarity utilities                   |
| **Data Management**            | openpyxl            | Latest              | Yes         | Excel read/write                       |
|                                | sqlalchemy          | Latest              | Optional    | External DB connectivity               |
| **Audio Processing**           | pydub               | Latest              | Optional    | Audio manipulation                     |
|                                | ffmpeg              | External dependency | Optional    | Audio decoding backend                 |
|                                | soundfile           | Latest              | Optional    | Audio IO                               |
| **Image Processing**           | Pillow (PIL)        | Latest              | Yes         | Image handling                         |
| **Utilities**                  | python-dotenv       | Latest              | Recommended | Environment variable loading           |
|                                | logging / traceback | Built-in            | Yes         | Runtime diagnostics                    |
|                                | rich                | Latest              | Optional    | Structured console output              |

## Disclaimer

## PyPI application

```powershell
python -m pip install buddy-py
buddy
```

`buddy` opens the tabless Windows WebView2 window by default. Standard browser
mode uses `buddy-browser`. Python 3.11 or 3.12 is recommended for the pinned
scientific dependencies. Windows requires Edge WebView2 Runtime.
The distribution is `buddy-py`; the import is `buddy`. Use a separate virtual
environment from the unrelated PyPI `buddy` distribution.
See [installation](resources/installation.md) and
[PyPI publishing](resources/pypi-release.md).

Budget Buddy is an analytical support tool. Outputs generated by large language models should be
independently reviewed and validated by qualified personnel before use in official decisions,
submissions, or policy actions.

## 📝 License

- Buddy is published under
  the [MIT General Public License v3 Jan 5, 2026](https://github.com/is-leeroy-jenkins/Boo/blob/main/LICENSE).
