boo-boo 0.1.0

Boo

Overview · Features · Modes · Requirements · Setup · Installation · Run · Configuration · Architecture · Capabilities ·

Boo is a Python application for running provider-aware artificial intelligence workflows across OpenAI GPT, Google Gemini, and xAI Grok. It supports text generation, image generation and analysis, image editing, audio transcription, audio translation, text-to-speech, embeddings, document question answering, file operations, vector stores, file-search stores, Google Cloud bucket workflows, prompt engineering, data export, and SQLite-backed data management.

Boo is designed for federal data analysis, budget execution support, document review, knowledge retrieval, prompt management, multimodal artificial intelligence experimentation, and controlled local analytical data operations.

🎥 Demo

☁️ Cloud

🧠 LLM

Boo includes a custom compact, instruction-tuned model package intended for local or edge-oriented experimentation. The Streamlit application itself is provider-aware and API-first, while the model artifact remains decoupled from the repository.

The model is useful for:

• Lightweight reasoning.
• Concise instruction following.
• Summarization.
• Light code synthesis.
• RAG-agent experimentation.
• Local or edge deployments where latency and footprint matter.

🧰 Overview

Boo wraps provider-specific helper modules and exposes them through a single Streamlit interface. The application uses a sidebar provider selector and a provider-filtered mode selector to present only workflows supported by the selected provider.

Provider modules imported by the application include:

The app initializes provider API keys, Google service keys, cloud settings, session-state defaults, provider-wrapper aliases, chat history, prompt records, embedding tables, and imported data tables. It then dispatches each mode through shared wrapper names such as Chat, Images, Embeddings, TTS, Transcription, Translation, Files, VectorStores, FileSearch, and CloudBuckets.

✨ Features

• Provider-aware interface for GPT, Gemini, and Grok workflows.
• Dynamic mode filtering so unsupported provider/mode combinations are hidden or blocked.
• Text generation controls for model, reasoning, modalities, media resolution, response count, temperature, Top-P, Top-K, frequency penalty, presence penalty, tools, include fields, tool choice, Google grounding, parallel tools, URL context, allowed domains, vector stores, collections, JSON schema output, stop sequences, storage, streaming, background execution, and conversation state.
• Image workflows for generation, analysis, and editing with provider-specific model routing, uploaded image handling, mask support, MIME/output options, aspect ratio, quality, style, background, grounding, image search, tools, includes, and rendered output history.
• Audio workflows for text-to-speech, transcription, and translation with uploaded files, browser recordings, playback controls, voice options, output format, sample rate, and runtime inference settings.
• Embedding mode with provider embedding models, encoding format, dimensions, chunk size, overlap, chunk inspection, embedding metrics, usage tracking, and vector output display.
• Document Q&A with local document loading, PyMuPDF extraction, chunking, embeddings, sqlite-vec retrieval when available, and cosine-similarity fallback.
• Files mode for provider file upload, metadata retrieval, deletion, listing, and file-backed workflows where supported.
• Vector Stores mode for creating, retrieving, deleting, batching, uploading, and attaching files to provider-supported vector stores or collection-like storage.
• File Search Stores mode for Gemini file-search store management.
• Google Cloud Buckets mode for Gemini/Google Cloud bucket creation, retrieval, deletion, and upload workflows.
• Prompt Engineering mode backed by the local SQLite Prompts table.
• Export mode for exporting local application data and assets where configured.
• Data Management mode for SQLite import, browsing, CRUD operations, profiling, filtering, aggregation, visualization, administration, and guarded SQL queries.
• Token usage tracking for last call and accumulated session usage where provider responses expose usage metadata.
• Fixed footer status bar showing provider, mode, model, and active runtime settings.

🧩 Application Modes

🛠️ Requirements

🔑 API Key Setup

Boo reads API and cloud configuration from config.py, environment variables, and Streamlit session state. Sidebar-entered values override configuration defaults for the current session and mirror the values into environment variables.

Helpful setup references:

• OpenAI API Key
• Grok API Key
• Gemini API Key

📦 Installation

1. Clone the Repository

git clone https://github.com/is-leeroy-jenkins/Boo.git
cd Boo

2. Create and Activate a Virtual Environment

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

Command Prompt:

python -m venv .venv
.venv\Scripts\activate.bat

macOS / Linux:

python -m venv .venv
source .venv/bin/activate

3. Install Dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

⚙️ Configuration

Set the required values in config.py, environment variables, or the Streamlit sidebar.

Example environment variables:

export OPENAI_API_KEY="your-openai-api-key"
export GEMINI_API_KEY="your-gemini-api-key"
export GOOGLE_API_KEY="your-google-api-key"
export GOOGLE_CSE_ID="your-google-custom-search-id"
export GOOGLEMAPS_API_KEY="your-google-maps-api-key"
export GEOCODING_API_KEY="your-geocoding-api-key"
export GEOAPIFY_API_KEY="your-geoapify-api-key"
export GOOGLE_CLOUD_PROJECT_ID="your-google-cloud-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export XAI_API_KEY="your-xai-api-key"

Windows PowerShell:

setx OPENAI_API_KEY "your-openai-api-key"
setx GEMINI_API_KEY "your-gemini-api-key"
setx GOOGLE_API_KEY "your-google-api-key"
setx GOOGLE_CSE_ID "your-google-custom-search-id"
setx GOOGLEMAPS_API_KEY "your-google-maps-api-key"
setx GEOCODING_API_KEY "your-geocoding-api-key"
setx GEOAPIFY_API_KEY "your-geoapify-api-key"
setx GOOGLE_CLOUD_PROJECT_ID "your-google-cloud-project-id"
setx GOOGLE_CLOUD_LOCATION "us-central1"
setx XAI_API_KEY "your-xai-api-key"

Important config.py objects include:

🚀 Running the Streamlit Application

From the project root:

streamlit run app.py

Once running, the application is available at:

http://localhost:8501

🧠 Provider Dispatch

Boo uses common wrapper names and provider-specific modules to keep the UI stable while switching between GPT, Gemini, and Grok.

The sidebar uses provider mode filtering so a provider only exposes modes that are configured and supported by the available wrapper classes.

💬 Text Generation

The Text mode provides provider-aware chat and text generation through the selected provider's Chat wrapper.

Supported control groups include:

Text mode supports:

• GPT vector store IDs for file-search-enabled responses.
• Gemini Google Search grounding.
• Gemini file-search store names when exposed by the wrapper.
• Grok collection IDs and configured xAI collection labels.
• Conversation or single-turn input modes.
• Provider-safe JSON schema payload construction for GPT and Grok.
• Source rendering when a provider wrapper exposes grounding or file-search sources.

📷 Images

The Images mode supports provider-aware image generation, image analysis, and image editing.

Image controls include:

• Workflow mode: Generation, Analysis, or Editing.
• Provider-specific image model selection.
• Response count.
• Temperature, Top-P, Top-K, frequency penalty, presence penalty, and max tokens.
• Tools, include fields, tool choice, allowed domains, max tool calls, and max searches.
• Google grounding and image-search options where supported.
• Image size, quality, style, background, aspect ratio, detail, compression, MIME type, output type, media resolution, and response modality.
• Uploaded image support for analysis and editing.
• Optional mask upload for editing where supported.
• Rendered image output from bytes, paths, URLs, dictionaries, provider objects, or lists.

🎧 Audio

The Audio mode supports provider-aware audio workflows.

Audio controls include:

• Task selection.
• Model selection.
• Voice selection.
• Output format.
• Language selection.
• Sample rate.
• Playback start and end time.
• Loop and autoplay.
• Temperature, Top-P, Top-K, frequency penalty, presence penalty, and max tokens.
• System prompt template support.
• Uploaded audio file or browser recording input.

🔢 Embeddings

The Embedding mode supports provider embedding workflows.

Embedding controls include:

• Embedding model selection.
• Encoding format selection.
• Dimension selection.
• Chunk-size control.
• Chunk-overlap control.
• Text input or file input where configured.
• Text normalization and chunking.
• Embedding vector generation.
• Metrics display.
• Chunk inspection.
• Usage metadata display.
• Data editor rendering for embedding vectors.

📓 Document Q&A

The Document Q&A mode supports retrieval-augmented document answering.

Supported document behavior includes:

• Uploading document bytes into Streamlit session state.
• Extracting PDF text with PyMuPDF where available.
• Defensive decoding for text-like files.
• Chunking document text.
• Generating local embeddings with sentence-transformers.
• Creating a sqlite-vec virtual table when available.
• Falling back to in-memory cosine similarity when vector-table retrieval is unavailable.
• Building document-grounded prompts from retrieved excerpts.
• Routing document prompts through the selected provider's Chat wrapper.

The document prompt instructs the model to answer from retrieved excerpts and state when the excerpts do not contain enough information.

📚 Files

The Files mode exposes provider file workflows through the selected provider's Files wrapper.

Common workflows include:

• File upload.
• File listing.
• File metadata retrieval.
• File deletion.
• File ID tracking.
• Provider-compatible temporary file saving.
• File-backed prompt workflows where supported.

🏛️ Vector Stores

The Vector Stores mode exposes provider vector-store or collection-like storage workflows.

Supported workflows include:

Supported upload types include:

• pdf
• txt
• md
• docx
• png
• jpg
• jpeg
• json
• csv

📦 File Search Stores

The File Search Stores mode supports Gemini file-search store management through the FileSearch wrapper. The mode is explicitly limited to Gemini and stops with a warning when another provider is selected.

Supported workflows include:

Supported upload types include:

• pdf
• txt
• md
• docx
• png
• jpg
• jpeg

🧊 Google Cloud Buckets

The Google Cloud Buckets mode supports Google Cloud bucket management through the CloudBuckets wrapper.

Supported workflows include:

📝 Prompt Engineering

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

Prompt records include:

Prompt Engineering supports:

• Prompt search.
• Prompt sorting.
• Prompt pagination.
• Prompt selection.
• Prompt editing.
• Prompt insertion.
• Prompt update.
• Prompt deletion.
• Cascading selected prompts into system instructions where configured.

📤 Export

The Export mode supports local export workflows where configured, including prompt, chat, data, or generated asset export paths.

🏛️ Data Management

The Data Management mode provides a SQLite administration and exploration interface.

Tabs include:

Visualization options include:

• Histogram.
• Bar chart.
• Line chart.
• Scatter plot.
• Box plot.
• Pie chart.
• Correlation heatmap.

SQL execution is guarded by a read-only validator that allows SELECT, WITH, EXPLAIN, and read-oriented PRAGMA statements while blocking destructive operations such as INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, DETACH, VACUUM, REPLACE, and TRIGGER.

🧩 Design and Architecture

Boo uses a provider-aware layered Streamlit architecture:

Architecture diagram:

┌──────────────────────────────────────────────┐
│                 Boo Streamlit App            │
│                                              │
│  Provider: GPT | Gemini | Grok               │
│                                              │
│  Modes: Text | Images | Audio | Embedding    │
│  Document Q&A | Files | Vector Stores        │
│  File Search Stores | Google Cloud Buckets   │
│  Prompt Engineering | Export | Data Mgmt     │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│            Provider Dispatch Layer           │
│                                              │
│  gpt.py | gemini.py | grok.py                │
│  Chat | Images | Embeddings | TTS            │
│  Transcription | Translation | Files         │
│  VectorStores | FileSearch | CloudBuckets    │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│             Configuration + State            │
│                                              │
│  config.py | environment variables           │
│  Streamlit session state                     │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│              SQLite Persistence              │
│                                              │
│  chat_history | embeddings | Prompts         │
│  imported data tables                        │
└──────────────────────────────────────────────┘

💻 Capabilities

📁 File Organization

🧪 Example Usage

Text Generation

from gpt import Chat

chat = Chat()
response = chat.generate_text(
    prompt="Explain how random forests reduce overfitting.",
    model="gpt-5-mini"
)

print(response)

Gemini Text Generation

from gemini import Chat

chat = Chat()
response = chat.generate_text(
    prompt="Summarize the purpose of retrieval augmented generation.",
    model="gemini-2.5-flash"
)

print(response)

Grok Text Generation

from grok import Chat

chat = Chat()
response = chat.generate_text(
    prompt="Create three concise bullets about semantic search.",
    model="grok-4"
)

print(response)

Embeddings

from gpt import Embeddings

embedding = Embeddings()
vectors = embedding.create(
    text=["Federal budget execution requires accurate obligations tracking."],
    model="text-embedding-3-small"
)

print(vectors)

Image Generation

from gpt import Images

images = Images()
result = images.generate(
    prompt="A clean technical diagram of a retrieval augmented generation pipeline.",
    model="gpt-image-1"
)

print(result)

Audio Transcription

from gpt import Transcription

transcriber = Transcription()
text = transcriber.transcribe("audio/meeting.m4a")

print(text)

SQLite Prompt Query

import sqlite3

with sqlite3.connect("stores/sqlite/Data.db") as conn:
    rows = conn.execute(
        "SELECT PromptsId, Caption, Name, Version FROM Prompts ORDER BY PromptsId DESC"
    ).fetchall()

print(rows)

🧮 Runtime Parameters

Boo exposes the following active runtime parameters across modes:

🧰 Troubleshooting

Documentation

The Boo documentation site is published with MkDocs Material and GitHub Pages.

Boo Documentation

🚀 Application Badges

📝 License

Boo is published under the MIT License.