How pdichone/ollama-fundamentals works
1. Repository shape
- This is not a single production app; it’s a collection of AI demo scripts centered on local LLM workflows, especially RAG over documents and tool/function calling.
- The code appears to be organized as separate entry points rather than one shared service.
2. Core theme: document-grounded LLM applications
- Several files are clearly variants of the same idea: ingest a document, chunk or clean it, build retrieval context, and answer user questions from that context.
- The main RAG-related scripts are:
- pdf-rag.py
- pdf-rag-clean.py
- pdf-rag-streamlit.py
- final-rag-voice.py
- start-1.py
- start-2.py
3. Data layer
- The data/ folder contains sample inputs used by the demos:
- data/BOI.pdf for PDF-based retrieval examples
- data/grocery_list.txt for a small text-based example or categorization/demo input
- These are reference corpora, not application state or persistent storage.
4. PDF ingestion and RAG pipeline
- The PDF scripts likely form the repo’s main pipeline:
- load PDF content
- clean or preprocess text
- split into chunks
- embed/index or otherwise prepare retrieval context
- answer questions using retrieved passages
- pdf-rag-clean.py suggests a preprocessing-focused variant, while pdf-rag.py is the simpler baseline.
5. Interactive interfaces
- pdf-rag-streamlit.py adds a Streamlit UI boundary on top of the RAG pipeline.
- This separates the retrieval/LLM logic from the user-facing interaction layer, making the architecture easy to diagram as:
- document processing backend
- interactive frontend
- shared LLM/retrieval core
6. Voice-enabled assistant flow
- final-rag-voice.py indicates a multimodal extension of the same document QA system.
- The architecture likely adds:
- speech input capture / transcription
- RAG query generation
- spoken or synthesized output
- This is a distinct interaction channel layered over the same document-grounded retrieval core.
7. Tool use / function calling
- function-calling.py is a separate demo for LLM tool invocation rather than document retrieval.
- Architecturally, it represents a second pattern in the repo:
- the model decides when to call tools/functions
- the application executes those actions
- results are returned back to the model or UI
- This is a boundary between model reasoning and deterministic application logic.
8. Text categorization utility
- categorizer.py appears to be a smaller utility or demo that likely classifies or organizes text inputs, probably using an LLM or rules.
- It likely consumes simple text data such as data/grocery_list.txt, showing a lightweight “input → classification/output” workflow separate from PDF RAG.
9. Model/runtime packaging
- Modelfile is an important architectural artifact: it indicates the repo is intended to run with a local model definition/runtime rather than only a hosted API.
- In diagrams, this should be shown as the model layer that the scripts call into, distinct from the Python application code.
10. Project organization and execution model
- commands_and_scripts.md suggests there are operating notes or run commands, which fits the repo’s “demo playground” nature.
- The .py files are likely standalone entry points, each demonstrating one workflow rather than sharing a central application server.
11. Dependencies and external boundaries
- requirements.txt defines the Python stack used across demos; the repo likely depends on libraries for PDF handling, retrieval/embedding, UI, and possibly speech or function-calling support.
- The main architectural boundary is between:
- local files and sample data
- Python orchestration scripts
- the model runtime / LLM backend
- optional UI or voice interfaces
12. How to diagram it
- A good architecture diagram would show multiple demo entry points feeding a shared AI/model layer:
- PDF ingestion/RAG path
- Streamlit UI path
- voice assistant path
- function-calling path
- categorization path
- The shared assets are the sample data files and the model definition; the main variation across scripts is the interaction mode and whether retrieval or tool execution is involved.
Main entry points: final-rag-voice.py Voice RAG · BOI.pdf BOI PDF · pdf-rag-clean.py Clean RAG · pdf-rag-streamlit.py Streamlit RAG
Components 18
Demo entry points
Standalone scripts that showcase different local LLM workflows.
- PDF RAG · Baseline PDF question-answering demo over retrieved document chunks.
pdf-rag.py - Clean RAG · Variant of the PDF RAG flow with extra preprocessing or cleanup.
pdf-rag-clean.py - Streamlit RAG · Interactive document Q&A demo with a Streamlit user interface.
pdf-rag-streamlit.py - Voice RAG · Voice-enabled document assistant that adds speech input or output to RAG.
final-rag-voice.py - Start 1 · Standalone RAG-style starter workflow for document-grounded prompting.
start-1.py - Start 2 · Second starter workflow, likely a variation on retrieval or prompt setup.
start-2.py - Tool Calling · Shows model-driven function or tool invocation with application-side execution.
function-calling.py - Categorizer · Small classification or organizing workflow for simple text inputs.
categorizer.py
Shared AI core
Common model runtime and document-grounded processing used by the demos.
- Modelfile · Local model definition and runtime configuration used by the demos.
Modelfile - RAG Core · Shared pattern of loading documents, chunking, retrieving context, and answering questions.
- Load Docs · Reads PDFs or text sources into usable content for downstream processing.
- Clean & Split · Normalizes text and breaks documents into chunks for retrieval.
- Retrieve Context · Selects the most relevant passages for a user query.
- Answer Model · Produces answers using retrieved context, prompts, or tool results.
- Voice I/O · Speech capture and spoken response boundary for the voice assistant demo.
- Tool Runtime · Deterministic application layer that executes model-requested functions.
Sample data
Reference inputs used by the repository's examples.
- BOI PDF · Reference PDF used by the document QA examples.
data/BOI.pdf - Grocery List · Small text sample used by the categorization or lightweight demo flow.
data/grocery_list.txt
Connections 21
- PDF RAG → RAG Core: uses · Baseline script drives the shared RAG workflow.
- Clean RAG → Clean & Split: preprocesses · Adds stronger text cleanup before retrieval.
- Clean RAG → RAG Core: uses · Feeds the cleaned content into the common retrieval flow.
- Streamlit RAG → RAG Core: wraps · Adds an interactive UI around the shared RAG logic.
- Voice RAG → Voice I/O: adds · Uses speech input or output as the interaction boundary.
- Voice RAG → RAG Core: uses · Keeps the same document-grounded answer core.
- Start 1 → RAG Core: uses · Starter script participates in the same retrieval pattern.
- Start 2 → RAG Core: uses · Second starter script participates in the same retrieval pattern.
- Tool Calling → Tool Runtime: routes to · Model decisions trigger deterministic tool execution.
- Tool Calling → Answer Model: returns to · Tool results are folded back into the model response.
- Categorizer → Answer Model: uses · Produces a classification or organization result from text input.
- RAG Core → Load Docs: starts with · Retrieval workflows begin by reading source documents.
- RAG Core → Clean & Split: prepares · Documents are normalized and chunked before indexing or retrieval.
- RAG Core → Retrieve Context: queries · Retrieval stage selects relevant passages for the prompt.
- RAG Core → Answer Model: finishes with · Generates the final response from context and question.
- Load Docs → BOI PDF: reads · PDF demos use the sample document as source material.
- Categorizer → Grocery List: reads · Text categorization demo can use the grocery list sample.
- Modelfile → Answer Model: configures · Local model definition underpins generation across demos.
- Modelfile → Tool Runtime: supports · Tool-use demos rely on the same local model runtime.
- Streamlit RAG → BOI PDF: loads · Interactive RAG demo points at the reference PDF.
- Voice RAG → BOI PDF: loads · Voice assistant variant also uses the document corpus.