# gold-pps/python-learning architecture

> Architecture diagram of the GitHub repository gold-pps/python-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gold-pps/python-learning
- Repository: https://github.com/gold-pps/python-learning

## Overview

This is a personal Python learning repository focused on Agent development, with `notes-qa` as its main product: a CLI accepts questions, runs an Agent with local-note tools, and returns cited answers through DeepSeek. The repository also contains a separate, optional RAG workflow: parse and chunk a corpus, build an incremental vector index, then evaluate retrieval and answer quality. Learning scripts demonstrate Agent concepts such as tools, memory, handoffs, guardrails, and evaluation. The graph reflects README capabilities; RAG-to-Agent integration is not established by the sampled source, so those flows remain separate.

Main entry points: [`agent-learning/notes-qa/rag/index.py`](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/index.py) (Index Builder), [`agent-learning/notes-qa/agent.py`](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/agent.py) (QA Agent), [`agent-learning/notes-qa/eval/rag_answer_eval.py`](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/rag_answer_eval.py) (Answer Evaluation), [`agent-learning/notes-qa/main.py`](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/main.py) (Interactive CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Agent Learning"]
  node_learning_exercises["Agent Exercises"]
  node_shared_setup["Shared Setup<br/>[_common.py]"]
end

subgraph group_assistant["Notes Assistant"]
  node_cli["Interactive CLI<br/>[main.py]"]
  node_agent["QA Agent<br/>[agent.py]"]
  node_tool_functions["Note Tools<br/>[tools.py]"]
  node_configuration["Model Configuration<br/>[config.py]"]
end

subgraph group_rag["RAG Retrieval"]
  node_rag_corpus["RAG Corpus"]
  node_parsers["Document Parsers<br/>[parsers.py]"]
  node_chunking["Chunking<br/>[chunker.py]"]
  node_embedding["Embedding<br/>[embedder.py]"]
  node_index_builder["Index Builder<br/>[index.py]"]
  node_index_store[("RAG Index")]
  node_retriever["Hybrid Retriever<br/>[retriever.py]"]
  node_reranker["LLM Reranker<br/>[rerank.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_retrieval_cases["Retrieval Cases<br/>[retrieval_cases.py]"]
  node_retrieval_eval["Retrieval Evaluation<br/>[rag_eval.py]"]
  node_answer_eval["Answer Evaluation<br/>[rag_answer_eval.py]"]
  node_answer_judge["Answer Judge<br/>[answer_judge.py]"]
end

node_learner(("Learner"))
node_cli_user(("Questioner"))
node_note_files["Markdown Notes"]
node_deepseek{{"DeepSeek API"}}

node_learner -->|"runs examples"| node_learning_exercises
node_learning_exercises -->|"imports setup"| node_shared_setup
node_cli_user -->|"asks question"| node_cli
node_cli -->|"runs Agent"| node_agent
node_agent -->|"dispatches tools"| node_tool_functions
node_tool_functions -->|"reads and searches"| node_note_files
node_cli -->|"uses limits"| node_configuration
node_agent -->|"uses model config"| node_configuration
node_configuration -->|"configures endpoint"| node_deepseek
node_agent -->|"requests completion"| node_deepseek
node_rag_corpus -->|"provides documents"| node_parsers
node_index_builder -->|"parses files"| node_parsers
node_index_builder -->|"chunks parsed text"| node_chunking
node_index_builder -->|"encodes chunks"| node_embedding
node_index_builder -->|"writes index files"| node_index_store
node_retriever -->|"loads index"| node_index_store
node_retrieval_cases -->|"supplies cases"| node_retrieval_eval
node_retrieval_eval -->|"measures search"| node_retriever
node_retrieval_eval -.->|"optionally reranks"| node_reranker
node_answer_eval -->|"retrieves context"| node_retriever
node_answer_eval -->|"requests answers"| node_deepseek
node_answer_eval -->|"judges answers"| node_answer_judge
node_retrieval_cases -->|"supplies cases"| node_answer_eval

click node_learning_exercises "https://github.com/gold-pps/python-learning/blob/main/agent-learning/04_multi_agent_handoff.py"
click node_shared_setup "https://github.com/gold-pps/python-learning/blob/main/agent-learning/_common.py"
click node_cli "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/main.py"
click node_agent "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/agent.py"
click node_tool_functions "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/tools.py"
click node_configuration "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/config.py"
click node_parsers "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/parsers.py"
click node_chunking "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/chunker.py"
click node_embedding "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/embedder.py"
click node_index_builder "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/index.py"
click node_retriever "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/retriever.py"
click node_reranker "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/rerank.py"
click node_retrieval_cases "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/retrieval_cases.py"
click node_retrieval_eval "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/rag_eval.py"
click node_answer_eval "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/rag_answer_eval.py"
click node_answer_judge "https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/answer_judge.py"

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_learning_exercises,node_shared_setup toneBlue
class node_cli,node_agent,node_tool_functions,node_configuration toneAmber
class node_rag_corpus,node_parsers,node_chunking,node_embedding,node_index_builder,node_index_store,node_retriever,node_reranker,node_deepseek toneMint
class node_retrieval_cases,node_retrieval_eval,node_answer_eval,node_answer_judge toneRose
class node_learner,node_cli_user,node_note_files toneIndigo
```

## Components

### Agent Learning

- [Agent Exercises](https://github.com/gold-pps/python-learning/blob/main/agent-learning/04_multi_agent_handoff.py): `agent-learning/04_multi_agent_handoff.py`
- [Shared Setup](https://github.com/gold-pps/python-learning/blob/main/agent-learning/_common.py): `agent-learning/_common.py`

### Notes Assistant

- [Interactive CLI](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/main.py): `agent-learning/notes-qa/main.py`
- [QA Agent](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/agent.py): `agent-learning/notes-qa/agent.py`
- [Note Tools](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/tools.py): `agent-learning/notes-qa/tools.py`
- [Model Configuration](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/config.py): `agent-learning/notes-qa/config.py`

### RAG Retrieval

- **RAG Corpus**
- [Document Parsers](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/parsers.py): `agent-learning/notes-qa/rag/parsers.py`
- [Chunking](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/chunker.py): `agent-learning/notes-qa/rag/chunker.py`
- [Embedding](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/embedder.py): `agent-learning/notes-qa/rag/embedder.py`
- [Index Builder](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/index.py): `agent-learning/notes-qa/rag/index.py`
- **RAG Index**
- [Hybrid Retriever](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/retriever.py): `agent-learning/notes-qa/rag/retriever.py`
- [LLM Reranker](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/rag/rerank.py): `agent-learning/notes-qa/rag/rerank.py`

### Evaluation

- [Retrieval Cases](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/retrieval_cases.py): `agent-learning/notes-qa/eval/retrieval_cases.py`
- [Retrieval Evaluation](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/rag_eval.py): `agent-learning/notes-qa/eval/rag_eval.py`
- [Answer Evaluation](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/rag_answer_eval.py): `agent-learning/notes-qa/eval/rag_answer_eval.py`
- [Answer Judge](https://github.com/gold-pps/python-learning/blob/main/agent-learning/notes-qa/eval/answer_judge.py): `agent-learning/notes-qa/eval/answer_judge.py`

### Other components

- **Learner**
- **Questioner**
- **Markdown Notes**
- **DeepSeek API**

## Connections

- Learner → Agent Exercises: runs examples
- Agent Exercises → Shared Setup: imports setup
- Questioner → Interactive CLI: asks question
- Interactive CLI → QA Agent: runs Agent
- QA Agent → Note Tools: dispatches tools
- Note Tools → Markdown Notes: reads and searches
- Interactive CLI → Model Configuration: uses limits
- QA Agent → Model Configuration: uses model config
- Model Configuration → DeepSeek API: configures endpoint
- QA Agent → DeepSeek API: requests completion
- RAG Corpus → Document Parsers: provides documents
- Index Builder → Document Parsers: parses files
- Index Builder → Chunking: chunks parsed text
- Index Builder → Embedding: encodes chunks
- Index Builder → RAG Index: writes index files
- Hybrid Retriever → RAG Index: loads index
- Retrieval Cases → Retrieval Evaluation: supplies cases
- Retrieval Evaluation → Hybrid Retriever: measures search
- Retrieval Evaluation → LLM Reranker: optionally reranks
- Answer Evaluation → Hybrid Retriever: retrieves context
- Answer Evaluation → DeepSeek API: requests answers
- Answer Evaluation → Answer Judge: judges answers
- Retrieval Cases → Answer Evaluation: supplies cases