Arsitektur Repository dan Peta Modul

Repository onlyphantom/llm-python bukan sebuah paket Python. Isinya kumpulan materi instruksional, contoh kode, dan script yang dirancang self-contained serta fokus tunggal, sehingga pembaca bisa memilih pola pemakaian yang relevan tanpa harus menjalankan seluruh rangkaian. README.md:3-5¹

Konsekuensi susunannya sederhana: tidak ada hierarki paket yang dalam. Hampir semua kode berada datar di akar repository sebagai script bernomor, mulai dari 00_start.py sampai 24_agents_guardrails.py. Pola penomoran ini dipakai konsisten ketika penulis menambahkan batch script baru, misalnya 19_agents_handsoff.py hingga 24_agents_guardrails.py pada Mei 2025 dan 15_sql.py hingga 18_chroma.py pada Februari 2025. README.md:40-53²

Peta direktori tingkat atas

Hanya dua direktori yang memuat kode yang bisa diimpor, yaitu utils/ dan workshop/. Sisanya adalah data, hasil persistensi, atau bahan prompt.

news/ adalah sumber data yang paling sering dipakai ulang. 01_qna.py memuatnya lewat DirectoryLoader('news', glob="**/*.txt"), memecahnya dengan CharacterTextSplitter(chunk_size=2500, chunk_overlap=0), lalu membangun Chroma.from_documents. 01_qna.py:12-21⁹ Jalur LlamaIndex memakai direktori yang sama lewat SimpleDirectoryReader('news') dan menyimpan hasilnya ke storage/ dengan index.storage_context.persist(). 02_llama.py:10-26¹⁰ Varian Chroma memakai data yang sama tetapi menulis ke koleksi newspieces melalui chromadb.PersistentClient(path="./storage"). 02b_llama_chroma.py:11-22¹¹

Ketergantungan antar modul

Diagram berikut memetakan sumber data, helper bersama, dan script yang membacanya. Arah panah berarti "dibaca oleh" atau "dipakai oleh".

graph TD
    NEWS["news/*.txt"]
    BOOK["book/*.html.txt"]
    STORAGE["storage/"]
    UTILS["utils/api_client.py"]
    QNA["01_qna.py"]
    LLAMA["02_llama.py"]
    CHROMA["02b_llama_chroma.py"]
    PINE["09_pinecone.py"]
    JOURNAL["10_journal.py"]
    CACHE["13_caching_memory.py, 13_caching_sqlite.py"]
    HF["05_hf.py"]
    CUSTOM["07_custom.py"]
    AGENTS["19-24 agent scripts"]

    NEWS -->|"DirectoryLoader"| QNA
    NEWS -->|"SimpleDirectoryReader"| LLAMA
    NEWS -->|"SimpleDirectoryReader"| CHROMA
    NEWS -->|"summary.txt"| CACHE
    BOOK -->|"scrape_book"| PINE
    QNA --> STORAGE
    LLAMA --> STORAGE
    CHROMA --> STORAGE
    PINE --> STORAGE
    JOURNAL -->|"ObsidianReader"| STORAGE
    UTILS -->|"retrieve_from_endpoint"| AGENTS
    HF ---|"transformers pipeline lokal"| CUSTOM

    style NEWS fill:#336791,color:#fff
    style BOOK fill:#336791,color:#fff
    style STORAGE fill:#336791,color:#fff
    style UTILS fill:#f59e0b,color:#000
    style CACHE fill:#8b5cf6,color:#fff
    style AGENTS fill:#2d7d46,color:#fff
    style HF fill:#dc2626,color:#fff
%% fig: Peta ketergantungan modul llm-python
%% desc: Script bernomor membaca data dari news/ atau book/, menyimpan index ke storage/, dan tiga script agent berbagi helper di utils/api_client.py.

Dua node berwarna khusus perlu penjelasan. 13_caching_sqlite.py memasang SQLiteCache(database_path=".langchain.db") sehingga hasil panggilan LLM tersimpan di berkas lokal. 13_caching_sqlite.py:9-13¹² Sementara itu 05_hf.py menandai jalur remote HuggingFace sebagai tidak terpakai: komentar di berkas itu menyebut pendekatan lama dikomentari karena masalah kompatibilitas, dan eksekusi dialihkan ke pipeline lokal. 05_hf.py:14-16¹³

Paket bantu utils/

Direktori utils/ hanya berisi __init__.py dan api_client.py. Berkas kedua inilah yang menjadi satu-satunya abstraksi bersama di repository ini. Isinya memuat .env lewat load_dotenv(), membaca SECTORS_API_KEY, menyusun header {"Authorization": SECTORS_API_KEY}, lalu mengekspos satu fungsi retrieve_from_endpoint(url: str) -> dict yang memanggil requests.get, memeriksa raise_for_status(), dan pada HTTPError menghentikan proses dengan raise SystemExit(err). utils/api_client.py:7-20³

Karena helper itu bergantung pada satu variabel lingkungan, ketiga pemakainya tidak bisa jalan tanpa SECTORS_API_KEY di .env. Variabel tersebut memang didokumentasikan sebagai optional di README bersama GROQ_API_KEY, PINECONE_API_KEY, dan beberapa kunci lain. README.md:85-101¹⁴

Duplikasi helper di jalur agent

Tidak semua script agent memakai utils/. 20_agents_tooluse.py mendefinisikan retrieve_from_endpoint sendiri di dalam berkas, sedangkan tiga script berikutnya mengimpornya dari paket bantu. 20_agents_tooluse.py:13¹⁵ Perbedaan ini penting saat membaca ulang kode: perbaikan pada utils/api_client.py hanya berlaku untuk 21_agents_deterministic.py, 23_agents_parallelization.py, dan 24_agents_guardrails.py. 21_agents_deterministic.py:15¹⁶ 23_agents_parallelization.py:13¹⁷ 24_agents_guardrails.py:35¹⁸

Materi workshop mengulang pola yang sama sekali lagi: workshop/ai-search-engine.py mendeklarasikan retrieve_from_endpoint secara mandiri, jadi berkas itu tidak terpengaruh perubahan di utils/. workshop/ai-search-engine.py:18¹⁹

Tiga jalur pustaka yang hidup berdampingan

Repository ini tidak memilih satu framework. Tiga jalur dipakai berdampingan, dan masing-masing punya berkas contoh sendiri.

Dua contoh LangChain yang paling rawan adalah 03_db.py dan 04_csv.py, karena keduanya mengeksekusi kode hasil generate model terhadap basis data dan CSV. Keduanya kini memakai ChatOpenAI dengan agent_type="openai-tools", dan 04_csv.py menambahkan allow_dangerous_code=True yang diwajibkan LangChain 1.x untuk eksekusi kode. 03_db.py:12-15²¹ 04_csv.py:14-16²³

⚠️ allow_dangerous_code=True memberi agent izin menjalankan kode Python yang dihasilkan model. Jalankan 04_csv.py hanya dengan dataset yang Anda percaya, dan jangan pernah mengarahkannya ke berkas produksi. 04_csv.py:14-16²³

Jalur LlamaIndex juga punya dua varian penyimpanan: index disimpan ke disk lewat StorageContext dan SimpleVectorStore, atau dititipkan ke Chroma lewat ChromaVectorStore. 02_llama.py:15-24⁷ 02b_llama_chroma.py:11-22¹¹

Titik masuk per topik

Karena script tidak saling mengimpor, pembaca masuk lewat topik, bukan lewat satu main. Pemetaan berikut menghubungkan berkas ke halaman dokumentasi yang membahasnya.

00_start.py adalah berkas terpendek di repository: ia hanya memanggil OpenAIEmbeddings().embed_documents([text]) pada satu kalimat lalu mencetak hasilnya. 00_start.py:1-11²⁴ Sementara 12_guidance_syntax.py menandai dirinya sebagai hasil migrasi dari guidance 0.x ke 1.x, dengan from guidance import models, gen, user, assistant dan models.OpenAI("gpt-3.5-turbo"). 12_guidance_syntax.py:11-16²⁵

Versi yang diuji dan jejak migrasi

requirements.txt mengunci versi secara eksplisit dan memakai komentar untuk menandai berkas mana yang membutuhkan paket tertentu. Beberapa penanda yang paling membantu saat menavigasi repository:

CHANGES.md mencatat alasan di balik penguncian itu. Judulnya menyebut sasaran kompatibilitas: LangChain 1.x, llama_index 0.10+, ChromaDB 1.x, dan OpenAI API 1.x. CHANGES.md:3-12³¹ Daftar versi kunci di bagian akhirnya menyebut langchain==1.2.10, chromadb==1.5.0, llama-index==0.14.15, dan Python 3.12. CHANGES.md:142-148³²

Dua berkas yang paling banyak berubah mengikuti migrasi ini adalah 02b_llama_chroma.py, yang beralih dari chromadb.Client() ke chromadb.PersistentClient(path="./storage") dan dari create_collection() ke get_or_create_collection(), CHANGES.md:98-100³³ serta 14_streamlit.py, yang memindahkan import langchain.agents ke langchain_classic.agents. CHANGES.md:126-127³⁴

Jebakan saat menavigasi repository

Beberapa hal di repository ini tidak konsisten dengan namanya sendiri, dan itu memperlambat pembacaan pertama.

1. README menulis nama berkas 22_agents_critic.py, sedangkan berkas yang benar-benar ada bernama 22_agents_judge_critic.py. README.md:40-53²
2. 03_db.py dan 04_csv.py menunjuk ke direktori academy/, padahal direktori itu tidak ada di akar repository. Keduanya tidak akan jalan tanpa dataset yang disediakan terpisah. 03_db.py:9-11³⁵ 04_csv.py:8-9³⁶
3. 10_journal.py mengunci OBSIDIAN_DIR ke sebuah path absolut milik penulis, sehingga wajib diubah sebelum dipakai. 10_journal.py:19-21³⁷
4. 07_custom.py mengeset os.environ["OPENAI_API_KEY"] = "random" agar tidak memanggil OpenAI sama sekali, sehingga kesalahan konfigurasi di berkas itu bukan tanda kunci API yang salah. 07_custom.py:14-26³⁸
5. requirements.txt mengomentari triton dan uvloop karena keduanya hanya untuk Linux, sesuai catatan README tentang triton yang hanya didukung pada arsitektur x86_64. requirements.txt:152-160³⁹ README.md:115-117⁴⁰

⚠️ Jalankan script dari akar repository. Banyak path di dalamnya relatif terhadap akar (news, storage, book), bukan terhadap lokasi berkas script, sehingga menjalankannya dari subdirektori akan gagal menemukan data. 01_qna.py:12-21⁹ 09_pinecone.py:28-33⁶