# pdichone/ollama-fundamentals architecture

> Architecture diagram of the GitHub repository pdichone/ollama-fundamentals, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pdichone/ollama-fundamentals
- Repository: https://github.com/pdichone/ollama-fundamentals

## Overview

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`](https://github.com/pdichone/ollama-fundamentals/blob/main/final-rag-voice.py) (Voice RAG), [`data/BOI.pdf`](https://github.com/pdichone/ollama-fundamentals/blob/main/data/BOI.pdf) (BOI PDF), [`pdf-rag-clean.py`](https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag-clean.py) (Clean RAG), [`pdf-rag-streamlit.py`](https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag-streamlit.py) (Streamlit RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_demos["Demo entry points"]
  node_node_pdf_rag["PDF RAG<br/>entry script<br/>[pdf-rag.py]"]
  node_node_pdf_rag_clean["Clean RAG<br/>entry script<br/>[pdf-rag-clean.py]"]
  node_node_pdf_rag_streamlit["Streamlit RAG<br/>ui demo"]
  node_node_final_rag_voice["Voice RAG<br/>multimodal demo<br/>[final-rag-voice.py]"]
  node_node_start_1["Start 1<br/>entry script<br/>[start-1.py]"]
  node_node_start_2["Start 2<br/>entry script<br/>[start-2.py]"]
  node_node_function_calling["Tool Calling<br/>LLM tool demo"]
  node_node_categorizer["Categorizer<br/>text demo<br/>[categorizer.py]"]
end

subgraph group_group_core["Shared AI core"]
  node_node_modelfile["Modelfile<br/>model config"]
  node_node_rag_core{{"RAG Core<br/>retrieval pipeline"}}
  node_node_doc_load["Load Docs<br/>ingestion stage"]
  node_node_clean_chunk["Clean & Split<br/>prep stage"]
  node_node_retrieve["Retrieve Context<br/>retrieval stage"]
  node_node_llm_answer(("Answer Model<br/>generation stage"))
  node_node_voice_io(("Voice I/O<br/>interface stage"))
  node_node_tools{{"Tool Runtime<br/>execution boundary"}}
end

subgraph group_group_data["Sample data"]
  node_node_pdf["BOI PDF<br/>sample document<br/>[BOI.pdf]"]
  node_node_grocery["Grocery List<br/>sample text<br/>[grocery_list.txt]"]
end

node_node_pdf_rag -->|"uses"| node_node_rag_core
node_node_pdf_rag_clean -->|"preprocesses"| node_node_clean_chunk
node_node_pdf_rag_clean -->|"uses"| node_node_rag_core
node_node_pdf_rag_streamlit -->|"wraps"| node_node_rag_core
node_node_final_rag_voice -->|"adds"| node_node_voice_io
node_node_final_rag_voice -->|"uses"| node_node_rag_core
node_node_start_1 -->|"uses"| node_node_rag_core
node_node_start_2 -->|"uses"| node_node_rag_core
node_node_function_calling -->|"routes to"| node_node_tools
node_node_function_calling -->|"returns to"| node_node_llm_answer
node_node_categorizer -->|"uses"| node_node_llm_answer
node_node_rag_core -->|"starts with"| node_node_doc_load
node_node_rag_core -->|"prepares"| node_node_clean_chunk
node_node_rag_core -->|"queries"| node_node_retrieve
node_node_rag_core -->|"finishes with"| node_node_llm_answer
node_node_doc_load -->|"reads"| node_node_pdf
node_node_categorizer -->|"reads"| node_node_grocery
node_node_modelfile -->|"configures"| node_node_llm_answer
node_node_modelfile -->|"supports"| node_node_tools
node_node_pdf_rag_streamlit -.->|"loads"| node_node_pdf
node_node_final_rag_voice -.->|"loads"| node_node_pdf

click node_node_pdf_rag "https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag.py"
click node_node_pdf_rag_clean "https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag-clean.py"
click node_node_pdf_rag_streamlit "https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag-streamlit.py"
click node_node_final_rag_voice "https://github.com/pdichone/ollama-fundamentals/blob/main/final-rag-voice.py"
click node_node_start_1 "https://github.com/pdichone/ollama-fundamentals/blob/main/start-1.py"
click node_node_start_2 "https://github.com/pdichone/ollama-fundamentals/blob/main/start-2.py"
click node_node_function_calling "https://github.com/pdichone/ollama-fundamentals/blob/main/function-calling.py"
click node_node_categorizer "https://github.com/pdichone/ollama-fundamentals/blob/main/categorizer.py"
click node_node_modelfile "https://github.com/pdichone/ollama-fundamentals/tree/main/Modelfile"
click node_node_pdf "https://github.com/pdichone/ollama-fundamentals/blob/main/data/BOI.pdf"
click node_node_grocery "https://github.com/pdichone/ollama-fundamentals/blob/main/data/grocery_list.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_pdf_rag,node_node_pdf_rag_clean,node_node_pdf_rag_streamlit,node_node_final_rag_voice,node_node_start_1,node_node_start_2,node_node_function_calling,node_node_categorizer toneBlue
class node_node_modelfile,node_node_rag_core,node_node_doc_load,node_node_clean_chunk,node_node_retrieve,node_node_llm_answer,node_node_voice_io,node_node_tools toneAmber
class node_node_pdf,node_node_grocery toneMint
```

## Components

### Demo entry points

Standalone scripts that showcase different local LLM workflows.

- [PDF RAG](https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag.py): entry script · Baseline PDF question-answering demo over retrieved document chunks. · `pdf-rag.py`
- [Clean RAG](https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag-clean.py): entry script · Variant of the PDF RAG flow with extra preprocessing or cleanup. · `pdf-rag-clean.py`
- [Streamlit RAG](https://github.com/pdichone/ollama-fundamentals/blob/main/pdf-rag-streamlit.py): ui demo · Interactive document Q&A demo with a Streamlit user interface. · `pdf-rag-streamlit.py`
- [Voice RAG](https://github.com/pdichone/ollama-fundamentals/blob/main/final-rag-voice.py): multimodal demo · Voice-enabled document assistant that adds speech input or output to RAG. · `final-rag-voice.py`
- [Start 1](https://github.com/pdichone/ollama-fundamentals/blob/main/start-1.py): entry script · Standalone RAG-style starter workflow for document-grounded prompting. · `start-1.py`
- [Start 2](https://github.com/pdichone/ollama-fundamentals/blob/main/start-2.py): entry script · Second starter workflow, likely a variation on retrieval or prompt setup. · `start-2.py`
- [Tool Calling](https://github.com/pdichone/ollama-fundamentals/blob/main/function-calling.py): LLM tool demo · Shows model-driven function or tool invocation with application-side execution. · `function-calling.py`
- [Categorizer](https://github.com/pdichone/ollama-fundamentals/blob/main/categorizer.py): text demo · 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](https://github.com/pdichone/ollama-fundamentals/tree/main/Modelfile): model config · Local model definition and runtime configuration used by the demos. · `Modelfile`
- **RAG Core**: retrieval pipeline · Shared pattern of loading documents, chunking, retrieving context, and answering questions.
- **Load Docs**: ingestion stage · Reads PDFs or text sources into usable content for downstream processing.
- **Clean & Split**: prep stage · Normalizes text and breaks documents into chunks for retrieval.
- **Retrieve Context**: retrieval stage · Selects the most relevant passages for a user query.
- **Answer Model**: generation stage · Produces answers using retrieved context, prompts, or tool results.
- **Voice I/O**: interface stage · Speech capture and spoken response boundary for the voice assistant demo.
- **Tool Runtime**: execution boundary · Deterministic application layer that executes model-requested functions.

### Sample data

Reference inputs used by the repository's examples.

- [BOI PDF](https://github.com/pdichone/ollama-fundamentals/blob/main/data/BOI.pdf): sample document · Reference PDF used by the document QA examples. · `data/BOI.pdf`
- [Grocery List](https://github.com/pdichone/ollama-fundamentals/blob/main/data/grocery_list.txt): sample text · Small text sample used by the categorization or lightweight demo flow. · `data/grocery_list.txt`

## Connections

- 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.