পুনরুৎপাদনযোগ্য প্রকল্প — folder, lockfile, data version আর Git

১ · পুনরুৎপাদনযোগ্যতা কী — একই রেসিপি, একই স্বাদ

“বাজারঘর” নামের কাল্পনিক অনলাইন দোকানের ডেটা টিমে রহিম একটি model বানালেন। Model বলে দেয় কোন অর্ডার দেরিতে পৌঁছাবে। রহিমের ল্যাপটপে accuracy এলো ০.৮৩। এক মাস পর ম্যানেজার জানতে চাইলেন, “সংখ্যাটা আবার দেখাতে পারবেন?” রহিম চালালেন, এলো ০.৮৭। সহকর্মী করিমের কম্পিউটারে একই notebook চালাতে গিয়ে আগে একটি error, package বদলানোর পর ০.৮৪। কোনটি সত্যি? কেউ জানেন না। ম্যানেজারের আস্থাও আর আগের মতো নেই।

সমস্যাটি model-এর নয়, প্রকল্পের। আর এর সমাধানই এই পর্বের বিষয়।

এই চারটির প্রতিটির জন্য আলাদা একটি হাতিয়ার আছে, আর এই পর্ব সেগুলো একে একে দেখাবে:

শব্দগুলো নিয়ে একটু সতর্ক থাকা ভালো, কারণ গবেষকেরা সবাই এক অর্থে ব্যবহার করেন না। এই কোর্সে reproducibility মানে একই code, একই ডেটা দিয়ে একই ফল পাওয়া — অন্য মানুষ, অন্য কম্পিউটারেও। Replicability মানে নতুন ডেটা বা নতুন করে লেখা code দিয়েও একই সিদ্ধান্তে পৌঁছানো; এটি আরও কঠিন পরীক্ষা। আর নিজের কম্পিউটারে নিজে আবার চালিয়ে একই ফল পাওয়াকে অনেকে বলেন repeatability. কিছু প্রতিষ্ঠান (যেমন ACM-এর একটি নির্দেশিকা) শব্দ দুটি প্রায় উল্টো অর্থে ব্যবহার করেছে; তাই কোনো লেখা পড়ার সময় সংজ্ঞাটি দেখে নেবেন।

এই পর্বের সব কাজ একটি সত্যিকারের ছোট প্রকল্পে করা হয়েছে, নাম bazarghar-ai. লেখার সময়ে ব্যবহার হয়েছে Python 3.13.5, uv 0.11.28, scikit-learn 1.9.1, pandas 3.1.0, NumPy 2.5.4, Git 2.53 আর DVC 3.67.1. এগুলো সময়ের সঙ্গে বদলাবে, তাই আপনার সংখ্যা মিলিয়ে দেখবেন। পাতার ভেতরে চালানো যায় এমন কোডগুলো চলে Pyodide-এ (সেখানে scikit-learn 1.8.0), তাই দুই জায়গার version আলাদা। এটিও reproducibility-র একটি শিক্ষা, যা পরে দেখব।

২ · প্রকল্পের ফোল্ডার — প্রতিটি জিনিসের নির্দিষ্ট তাক

পাড়ার মুদি দোকানে চাল এক তাকে, ডাল আরেক তাকে, আর হিসাবের খাতা ক্যাশবাক্সের পাশে। নতুন কর্মচারী প্রথম দিনেই জিনিস খুঁজে পান। AI প্রকল্পেও এমন নির্দিষ্ট তাক দরকার। প্রচলিত একটি কাঠামো নিচে, আর পাশে লেখা আছে কোনটি Git-এ যায় আর কোনটি যায় না।

এই কাঠামোর পেছনে তিনটি সহজ নিয়ম আছে:

1. মূল ডেটা কখনো বদলাবেন না। Raw data হলো আদালতের প্রমাণের মতো — একবার জমা পড়লে কেউ তাতে কলম ছোঁয়ায় না। Excel-এ খুলে একটি ভুল মান হাতে ঠিক করলে কেউ জানবে না কী বদলাল, কেন বদলাল। তার বদলে পরিষ্কার করার কাজ একটি script-এ লিখুন, যা data/raw পড়ে data/processed-এ নতুন ফাইল লেখে। ভুল হলে script সংশোধন করে আবার চালালেই হলো।
2. যা আবার তৈরি করা যায়, তা Git-এ রাখার দরকার নেই। Processed ডেটা আর trained model দুটোই code চালালে ফিরে আসে। Git-এ রাখতে হয় যা দিয়ে এগুলো তৈরি হয় — code, ছোট মূল ডেটা আর lockfile.
3. Notebook খোঁজার জন্য, src চালানোর জন্য। Notebook-এ ডেটা দেখা, চিত্র আঁকা, ধারণা যাচাই। কিন্তু যে ধাপগুলো বারবার চলবে (ডেটা তৈরি, train, মূল্যায়ন), সেগুলো src/-এর .py ফাইলে রাখুন, যাতে একটি কমান্ডেই উপর থেকে নিচ পর্যন্ত চলে। Notebook-এর cell এলোমেলো ক্রমে চালালে কী সমস্যা হয়, তা পর্ব ৮ (Jupyter notebook — cell, kernel, magic আর ভালো অভ্যাস)-এর বিষয়।

একটি প্রকল্পের ফাইল-তালিকা দেখে এই নিয়মগুলো মানা হয়েছে কি না, তা ছোট একটি Python ফাংশনই যাচাই করতে পারে। নিচের কোডটি একটি শেখানোর মডেল: আসল প্রকল্পে তালিকাটি আসত git ls-files থেকে, এখানে হাতে দেওয়া। প্রথমবার “চালান” চাপলে Python লোড হতে কয়েক সেকেন্ড লাগবে।

REQUIRED = ["data/raw/", "data/processed/", "notebooks/", "src/", "models/", "reports/"]
MUST_HAVE = ["pyproject.toml", "uv.lock", ".gitignore", "README.md"]
SECRET_HINTS = (".env", ".key", "secret", "password")
MAX_GIT_MB = 50                         # a team rule, not a Git limit

# (path, size in MB, tracked by Git?)
files = [
    ("pyproject.toml", 0.01, True), ("uv.lock", 0.05, True),
    (".gitignore", 0.01, True), ("src/train.py", 0.01, True),
    ("data/raw/orders.csv", 0.01, True), ("data/raw/reviews_2026.csv", 180, True),
    ("data/processed/clean.parquet", 2, False), ("notebooks/explore.ipynb", 0.3, True),
    ("models/model.joblib", 4, False), ("reports/metrics.json", 0.01, True),
    (".env", 0.01, True),
]

paths = [p for p, _, _ in files]
problems = []
for folder in REQUIRED:
    if not any(p.startswith(folder) for p in paths):
        problems.append(f"missing folder: {folder}")
for name in MUST_HAVE:
    if name not in paths:
        problems.append(f"missing file: {name}")
for p, mb, tracked in files:
    if tracked and any(h in p.lower() for h in SECRET_HINTS):
        problems.append(f"secret in Git: {p}")
    if tracked and mb > MAX_GIT_MB:
        problems.append(f"too big for Git ({mb} MB): {p} -> DVC/LFS")

print(len(files), "paths checked")
print("\n".join(problems) if problems else "OK: layout looks reproducible")

11 paths checked
missing file: README.md
too big for Git (180 MB): data/raw/reviews_2026.csv -> DVC/LFS
secret in Git: .env

৩ · Environment বেঁধে রাখা — pyproject, uv.lock আর Python version

Python install, virtual environment আর uv-এর খুঁটিনাটি পর্ব ৭ (AI-এর জন্য Python — install, uv, venv আর package)-এ। Python ভাষার দিক থেকে venv আর pyproject.toml বোঝার জন্য আছে Python কোর্সের pip, virtual environment আর pyproject পর্ব। এখানে শুধু একটি প্রশ্ন: অন্য কম্পিউটারে হুবহু একই package কীভাবে ফিরিয়ে আনবেন?

দুটি ফাইলের পার্থক্য বুঝলেই উত্তর পরিষ্কার। pyproject.toml হলো বাজারের ফর্দ: “চাল লাগবে, ৫ কেজির কম নয়।” আর uv.lock হলো দোকানের রসিদ: “মিনিকেট, অমুক ব্যাচ, ৫ কেজি, এই ওজনে।” ফর্দ দিয়ে আবার বাজার করলে অন্য ব্যাচ আসতে পারে; রসিদ দিয়ে করলে হুবহু একই জিনিস।

সত্যিকারের run (Windows-এ Git Bash, uv 0.11.28; ফোল্ডারের পথ সরিয়ে ~/bazarghar-ai লেখা হয়েছে):

$ uv init bazarghar-ai --app --python 3.13 --vcs none
Initialized project `bazarghar-ai` at `~/bazarghar-ai`
$ cd bazarghar-ai
$ uv add scikit-learn pandas
Using CPython 3.13.5 interpreter at: …
Creating virtual environment at: .venv
Resolved 11 packages in 1.57s
Prepared 4 packages in 1m 27s
Installed 10 packages in 1.46s
 + cloudpickle==3.1.2
 + joblib==1.6.0
 + narwhals==2.28.0
 + numpy==2.5.4
 + pandas==3.1.0
 + python-dateutil==4.0.0
 + scikit-learn==1.9.1
 + scipy==1.18.1
 + threadpoolctl==3.7.0
 + tzdata==2026.6

আপনি চেয়েছেন মাত্র দুটি package, কিন্তু এসেছে দশটি। বাকিগুলো তাদের dependency — scikit-learn-এর জন্য NumPy, SciPy, joblib; pandas-এর জন্য python-dateutil, tzdata. এদের যেকোনো একটির version বদলালেও ফল বদলাতে পারে। এবার দুটি ফাইলের ভেতরে দেখুন:

$ cat pyproject.toml
[project]
name = "bazarghar-ai"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "pandas>=3.1.0",
    "scikit-learn>=1.9.1",
]

$ grep -A12 'name = "scikit-learn"' uv.lock
name = "scikit-learn"
version = "1.9.1"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "joblib" },
    { name = "narwhals" },
    { name = "numpy" },
    { name = "scipy" },
    { name = "threadpoolctl" },
]
sdist = { url = "https://files.pythonhosted.org/…", hash = "sha256:…" }
wheels = [
    { url = "https://files.pythonhosted.org/…", hash = "sha256:…" },
…

pyproject.toml বলছে “৩.১.০ বা তার বেশি” — ফর্দ। uv.lock (মোট ৩০৭ লাইন) বলছে “হুবহু ১.৯.১, এই ফাইল, এই hash” — রসিদ, আর শুধু scikit-learn নয়, দশটি package-এরই। .python-version ফাইলে লেখা আছে 3.13, যাতে Python-এর version-ও না বদলায়। তিনটি ফাইলই Git-এ যায়; .venv/ ফোল্ডারটি যায় না, কারণ lockfile থেকে সেটি যেকোনো সময় আবার বানানো যায়।

Lockfile পুরোনো হয়ে গেলে কী হয়? দ্বিতীয় একটি কপিতে pyproject.toml-এ হাতে matplotlib যোগ করা হলো, কিন্তু uv lock চালানো হলো না। সত্যিকারের run:

$ uv sync --locked
Resolved 19 packages in 427ms
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

hint: To update the lockfile, run `uv lock`.

এটিই চাই। --locked মানে “ফর্দ আর রসিদ না মিললে থামো।” না থামলে আপনি ভাবতেন হুবহু একই environment পেয়েছেন, আসলে পেতেন নতুন কিছু। শুধু lockfile থেকে বসাতে চাইলে, মিলিয়ে না দেখে, আছে --frozen; কিন্তু reproducibility যাচাইয়ের সময় --locked নিরাপদ।

৪ · ডেটার আঙুলের ছাপ — hash

Code-এর version চেনা সহজ — Git-এর commit hash. কিন্তু ডেটা? “orders_final_v2_আসল.csv” নামে ভরসা নেই। দরকার এমন একটি ছোট চিহ্ন, যা ফাইলের প্রতিটি byte থেকে হিসাব করা হয়, যাতে একটি সংখ্যাও বদলালে চিহ্নটি বদলে যায়। এটাই hash function-এর কাজ।

একটি ভালো cryptographic hash-এর তিনটি গুণ এখানে কাজে লাগে:

• নির্ধারিত (deterministic): একই byte দিলে যেকোনো কম্পিউটারে, যেকোনো সময়, একই ছাপ।
• Avalanche: একটি bit বদলালে ছাপের প্রায় অর্ধেক bit বদলে যায়; দেখে বোঝার উপায় থাকে না যে দুটি ফাইল “প্রায় একই”।
• সংঘাত প্রায় অসম্ভব: আলাদা দুটি ফাইলের একই ছাপ পাওয়া তাত্ত্বিকভাবে সম্ভব, কিন্তু বাস্তবে নয়। SHA-256-এর সম্ভাব্য ছাপ 2²⁵⁶টি। “Birthday bound” অনুযায়ী এলোমেলো ফাইল থেকে একটি সংঘাত পেতে মোটামুটি 2¹²⁸ ≈ 3.4 × 10³⁸টি ফাইল লাগবে। পৃথিবীর সব কম্পিউটার মিলেও এত ফাইল বানানো সম্ভব নয়।

নিচের কোডটি bazarghar-ai-এর আসল data/raw/orders.csv (৪০০টি অর্ডার, পাতার ভেতরে রাখা) পড়ে তার ছাপ নেয়, তারপর একটিমাত্র মান বদলে আবার ছাপ নেয়:

import hashlib
from pathlib import Path

def sha256_of(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()

raw = Path("data/raw/orders.csv").read_bytes()
h1 = sha256_of(raw)
print("rows:", raw.count(b"\n") - 1, "| bytes:", len(raw))
print("original :", h1[:16])

# one value changes: first order's late 0 -> 1
edited = raw.replace(b"15.7,1,28.7,0", b"15.7,1,28.7,1", 1)
h2 = sha256_of(edited)
print("one edit :", h2[:16])
same = sum(a == b for a, b in zip(h1, h2))
print("same file?", h1 == h2, "| matching hex digits:", same, "of", len(h1))

# only the line endings change (Windows CRLF)
h3 = sha256_of(raw.replace(b"\n", b"\r\n"))
print("CRLF copy:", h3[:16], "| same as original?", h3 == h1)

# same bytes again -> same hash, every time, on every computer
print("re-hash  :", sha256_of(raw)[:16], "| stable?", sha256_of(raw) == h1)

rows: 400 | bytes: 5367
original : 6dc23919dc729ae6
one edit : c6789d1af4631f89
same file? False | matching hex digits: 5 of 64
CRLF copy: 88c7cf382539cb7e | same as original? False
re-hash  : 6dc23919dc729ae6 | stable? True

এবার একই ঘটনা সত্যিকারের প্রকল্পে। train.py প্রতিবার চলার সময় ডেটার SHA-256 হিসাব করে ছাপে আর log-এ লেখে। একটি কপিতে কেউ প্রথম অর্ডারের late মান হাতে বদলে দিলেন। প্রতিটি সংখ্যা সত্যিকারের run থেকে নেওয়া:

৫ · ছোট ডেটা Git-এ, বড় ডেটা বাইরে — DVC আর Git LFS

Data versioning-এর সবচেয়ে সহজ উপায় হলো ডেটা সরাসরি Git-এ রাখা। bazarghar-ai-এর orders.csv মাত্র ৫ KB, তাই এটি Git-এই আছে, আর আগের stepper-এ দেখলেন এতে কত সুবিধা। কিন্তু Git তৈরি হয়েছিল code-এর জন্য। প্রতিটি clone পুরো ইতিহাস নামায়; ২০০ MB-এর একটি ফাইল দশবার বদলালে repository প্রায় ২ GB, আর প্রত্যেক নতুন সহকর্মীকে সবটা নামাতে হবে। জনপ্রিয় hosting সেবাগুলোও ফাইলের আকারে সীমা দেয় (লেখার সময়ে GitHub সাধারণ Git-এ ১০০ MB-এর বেশি ফাইল নেয় না, ৫০ MB-এর ওপরে সতর্ক করে)।

সমাধানের মূল ভাবনা দুই টুলেই এক: Git-এ রাখুন ছোট একটি চিরকুট, আসল ফাইল রাখুন অন্য গুদামে। চিরকুটে লেখা থাকে ফাইলের hash; hash মিলিয়ে গুদাম থেকে ঠিক সেই version নামানো যায়।

DVC এই পর্বের জন্য একটি আলাদা scratch ফোল্ডারে আলাদা virtual environment-এ বসানো হয়েছিল (DVC 3.67.1). সত্যিকারের run, একই orders.csv নিয়ে (DVC-র লম্বা স্বাগত-বার্তার একটি অংশ “…” দিয়ে ছাঁটা):

$ git init -q
$ dvc init
Initialized DVC repository.

You can now commit the changes to git.
…
$ dvc add data/raw/orders.csv

To track the changes with git, run:

	git add 'data\raw\orders.csv.dvc' 'data\raw\.gitignore'
…
$ cat data/raw/orders.csv.dvc
outs:
- md5: a602c3fbca1de19ea5b7e4a495de5fb0
  size: 5367
  hash: md5
  path: orders.csv
$ cat data/raw/.gitignore
/orders.csv
$ dvc remote add -d store ../dvc-store
Setting 'store' as a default remote.
$ dvc push
1 file pushed

লক্ষ করুন কী ঘটল। DVC ফাইলটির MD5 ছাপ নিয়ে (a602c3fb…) একটি ৫ লাইনের orders.csv.dvc চিরকুট বানাল, আর .gitignore-এ আসল ফাইলটি যোগ করে দিল, যাতে সেটি ভুলেও Git-এ না যায়। Git-এ যাবে শুধু চিরকুট; আসল ফাইল গেল dvc-store নামের “গুদামে”। এবার ডেটার একটি মান বদলে দেখা হলো:

$ dvc status
data\raw\orders.csv.dvc:
	changed outs:
		modified:           data\raw\orders.csv
$ dvc checkout --force
M       data\raw\orders.csv
$ dvc status
Data and pipelines are up to date.

DVC ছাপ মিলিয়ে বদল ধরল, আর dvc checkout গুদাম থেকে মূল version ফিরিয়ে আনল। অন্য কেউ repository clone করলে dvc pull দিয়ে চিরকুটে লেখা version-টিই পাবেন। Git LFS এই পর্বে চালানো হয়নি; এর কাজের ধারা একই রকম, শুধু কমান্ড git lfs track "*.parquet" ধরনের।

৬ · .gitignore আর গোপন তথ্য — যা কখনো Git-এ যাবে না

Git-এর মৌলিক কাজ (init, add, commit, তিনটি এলাকা) এই কোর্সে আবার শেখানো হবে না; সেগুলো আছে Software Engineering & Git কোর্সের প্রথম Git repository পর্বে, আর .gitignore-এর নিয়মের খুঁটিনাটি .gitignore, .gitattributes আর git config পর্বে। এখানে শুধু ডেটা-বিজ্ঞানের প্রকল্পে কোন জিনিস বাদ দিতে হয়, তা। bazarghar-ai-এর আসল .gitignore:

# Python and the environment (rebuilt from uv.lock)
__pycache__/
*.py[cod]
.venv/

# Jupyter
.ipynb_checkpoints/

# Data: processed files are rebuilt by code; big raw files live outside Git
data/processed/
data/raw/*
!data/raw/orders.csv

# Trained models and the local experiment log
models/
reports/experiments.jsonl

# Secrets: never in Git
.env
*.key

data/raw/* লাইনটি raw ফোল্ডারের সবকিছু বাদ দেয়, আর !data/raw/orders.csv (! মানে “বাদ দিও না”) শুধু ছোট ফাইলটিকে আবার ঢোকায়। এতে কেউ ভুলে বড় একটি ফাইল raw ফোল্ডারে রাখলেও সেটি Git-এ যাবে না। সত্যিকারের repository-তে git ls-files দেখাল ঠিক ১১টি ফাইল: .gitignore, .python-version, README.md, data/raw/orders.csv, notebooks/.gitkeep, params.json, pyproject.toml, reports/metrics.json, src/make_data.py, src/train.py আর uv.lock. খালি ফোল্ডার Git রাখে না, তাই notebooks/-এ একটি খালি .gitkeep ফাইল রাখা হয়েছে।

Secret আর ব্যক্তিগত ডেটা

AI প্রকল্পে প্রায়ই database-এর password, cloud-এর key বা কোনো API-র token লাগে। এগুলো secret. Notebook-এর একটি cell-এ API_KEY = "…" লিখে commit করলে key-টি Git-এর ইতিহাসে স্থায়ী হয়ে যায়। পরের commit-এ লাইনটি মুছলেও আগের commit-এ সেটি থেকে যায়, আর public repository-তে স্বয়ংক্রিয় bot কয়েক মিনিটের মধ্যেই এমন key খুঁজে বের করতে পারে বলে নিরাপত্তা-গবেষকেরা বারবার সতর্ক করেছেন।

• Secret থাকবে .env ফাইলে বা environment variable-এ, আর .env থাকবে .gitignore-এ। Repository-তে রাখুন শুধু একটি .env.example, যাতে নাম আছে কিন্তু মান নকল: DB_PASSWORD=example-secret.
• ভুলে commit হয়ে গেলে আগে key বাতিল করুন (rotate), তারপর ইতিহাস পরিষ্কারের কথা ভাবুন। ইতিহাস মোছার পদ্ধতি আর secret-scanning টুল আছে Git-এ নিরাপত্তা পর্বে।
• ব্যক্তিগত ডেটা Git-এ নয়। ক্রেতার নাম, ফোন নম্বর, ঠিকানা, জাতীয় পরিচয়পত্র নম্বর বা bKash নম্বর থাকা ফাইল কখনো Git-এ তুলবেন না, private repository হলেও না; repository কপি হয়, ল্যাপটপ হারায়, অ্যাক্সেস বদলায়। Model শেখার জন্য সাধারণত এগুলো লাগেই না। দরকার হলে আগে সরিয়ে বা ছদ্মনাম দিয়ে (pseudonymise) তারপর কাজ। Data protection-এর বড় আলোচনা পর্ব ৬-এ আর পরের ধাপের AI নৈতিকতার কোর্সে।

৭ · Experiment-এর খাতা — parameter, ডেটার ছাপ, code version আর metrics

ক্রিকেটের স্কোরকার্ডে শুধু মোট রান লেখা থাকে না; কে, কোন ওভারে, কোন বলে কত রান — সব। এক মাস পরেও যে কেউ খেলাটি নতুন করে “পড়তে” পারেন। Model train করাও একরকম খেলা, আর তার স্কোরকার্ড হলো experiment log. প্রতিটি run-এ কমপক্ষে চারটি জিনিস লিখতে হয়:

1. Parameter: seed, test_size, model-এর hyperparameter (যেমন logistic regression-এর C). bazarghar-ai-এ এগুলো code-এর ভেতরে নয়, আলাদা params.json ফাইলে: {"seed": 42, "test_size": 0.25, "C": 1.0}.
2. ডেটার ছাপ: SHA-256-এর প্রথম ১২ অক্ষর যথেষ্ট।
3. Code-এর version: git rev-parse --short HEAD থেকে পাওয়া commit hash, আর library-র version (অন্তত scikit-learn-এর)।
4. Metrics: accuracy, F1 বা যা আপনার সমস্যার জন্য ঠিক।

Log-এর ধরন হিসেবে JSON Lines খুব সুবিধাজনক: প্রতিটি run একটি লাইন, নতুন run মানে ফাইলের শেষে একটি নতুন লাইন, আগের কিছু বদলায় না। নিচের পাতায় রাখা ফাইলে train.py-এর লেখা আসল চারটি লাইন আছে। কোডটি একটি নতুন run যোগ করে, তারপর পুরো log টেবিল হিসেবে পড়ে:

import json
import pandas as pd

LOG = "reports/experiments.jsonl"

def log_run(commit, data_sha256, params, metrics):
    entry = {"commit": commit, "data_sha256": data_sha256,
             "params": params, "sklearn": "1.9.1", **metrics}
    with open(LOG, "a", encoding="utf-8") as f:   # "a" = append, never overwrite
        f.write(json.dumps(entry) + "\n")

# a new run: same code and data, but the split seed was removed
log_run("b25370c", "6dc23919dc72",
        {"seed": None, "test_size": 0.25, "C": 1.0},
        {"accuracy": 0.84, "f1": 0.8095})

with open(LOG, encoding="utf-8") as f:
    rows = [json.loads(line) for line in f if line.strip()]
log = pd.json_normalize(rows).rename(columns=lambda c: c.replace("params.", ""))
log["seed"] = log["seed"].astype("Int64")
print(log[["commit", "data_sha256", "seed", "C", "accuracy", "f1"]].to_string())
print()
print("runs:", len(log), "| data versions:", log["data_sha256"].nunique())
seeded = log[log["seed"].notna()]
best = seeded["f1"].max()
print("seeded runs, best f1:", best,
      "at C =", seeded.loc[seeded["f1"] == best, "C"].tolist())
print("unseeded runs:", int(log["seed"].isna().sum()), "-> cannot be repeated exactly")

    commit   data_sha256  seed      C  accuracy      f1
0  cc09fc3  6dc23919dc72    42   1.00      0.83  0.8000
1  b25370c  6dc23919dc72    42   0.01      0.82  0.7805
2  b25370c  6dc23919dc72    42   0.10      0.83  0.8000
3  b25370c  6dc23919dc72    42  10.00      0.83  0.8000
4  b25370c  6dc23919dc72  <NA>   1.00      0.84  0.8095

runs: 5 | data versions: 1
seeded runs, best f1: 0.8 at C = [1.0, 0.1, 10.0]
unseeded runs: 1 -> cannot be repeated exactly

এবার log পড়ে তুলনা করা যাক। নিচের stepper-এ log-এর প্রতিটি লাইন একে একে আসছে:

ছোট প্রকল্পে এই JSONL বা একটি CSV ফাইলই যথেষ্ট। Run-এর সংখ্যা শতাধিক হলে, দলের অনেকে একসঙ্গে কাজ করলে, বা প্রতিটি run-এর chart আর model ফাইলও রাখতে হলে বিশেষ টুল কাজে লাগে। বহুল ব্যবহৃত একটি open-source বিকল্প MLflow: mlflow.log_param, mlflow.log_metric ধরনের ফাংশনে একই চারটি জিনিস লেখে আর ব্রাউজারে তুলনার পাতা দেখায়। এই পর্বে MLflow চালানো হয়নি; এর ব্যবহার পরের ধাপের কোর্সে আসবে। মনে রাখবেন, টুল বদলালেও কী লিখতে হবে তা বদলায় না।

৮ · পুরো পথ — clone থেকে হুবহু একই metrics

এতক্ষণের সব টুকরো জোড়া দেওয়ার সময়। bazarghar-ai-এর দুটি script:

• src/make_data.py: np.random.default_rng(42) দিয়ে ৪০০টি কাল্পনিক অর্ডার বানায় (দূরত্ব, পণ্যের সংখ্যা, বৃষ্টি, দেরি হয়েছে কি না) আর data/raw/orders.csv-এ লেখে।
• src/train.py: params.json পড়ে, ডেটার SHA-256 নেয়, random_state দিয়ে train-test split করে (৩০০ শেখার জন্য, ১০০ যাচাইয়ের জন্য), scikit-learn-এর logistic regression train করে, আর reports/metrics.json লেখে, সঙ্গে log-এ একটি লাইন।

train.py-এর মূল অংশটুকু (পুরো ফাইল ৩৭ লাইন):

params = json.loads(Path("params.json").read_text())
raw = Path("data/raw/orders.csv")
data_hash = hashlib.sha256(raw.read_bytes()).hexdigest()

df = pd.read_csv(raw)
X, y = df[["distance_km", "items", "rain_mm"]], df["late"]
X_tr, X_te, y_tr, y_te = train_test_split(
    X, y, test_size=params["test_size"], random_state=params["seed"], stratify=y)

model = LogisticRegression(C=params["C"], max_iter=1000).fit(X_tr, y_tr)
pred = model.predict(X_te)
metrics = {"accuracy": round(accuracy_score(y_te, pred), 4),
           "f1": round(f1_score(y_te, pred), 4)}
Path("reports/metrics.json").write_text(json.dumps(metrics, indent=2) + "\n")

প্রথম কম্পিউটারে (Git-এর লেখক হিসেবে কাল্পনিক “Rahim”) data তৈরি, commit, train, তারপর metrics commit. সত্যিকারের run:

$ uv run python src/make_data.py
wrote data/raw/orders.csv rows: 400
$ sha256sum data/raw/orders.csv
6dc23919dc729ae61dda11755c48e3ffa8ff94c4e480051bb4d56cf0ac03243f *data/raw/orders.csv
$ git init
Initialized empty Git repository in ~/bazarghar-ai/.git/
$ git add .
$ git commit -q -m "Bazarghar late-delivery model: data, code, lockfile"
$ uv run python src/train.py
data sha256: 6dc23919dc72
metrics    : {'accuracy': 0.83, 'f1': 0.8}
$ git add reports/metrics.json
$ git commit -q -m "Baseline metrics (seed 42)"
$ git log --format="%h %an <%ae> %s"
b25370c Rahim <rahim@example.com> Baseline metrics (seed 42)
cc09fc3 Rahim <rahim@example.com> Bazarghar late-delivery model: data, code, lockfile

এবার আসল পরীক্ষা: সম্পূর্ণ নতুন একটি ফোল্ডারে, যেখানে কোনো .venv নেই, কোনো পুরোনো ফাইল নেই। এটি করিমের ল্যাপটপের প্রতিনিধি। নিচের stepper-এ প্রতিটি ধাপের সত্যিকারের আউটপুট দেখুন:

$ git clone ../bazarghar-ai
Cloning into 'bazarghar-ai'...
done.
$ ls -a bazarghar-ai
.  ..  .git  .gitignore  .python-version  README.md
data  notebooks  params.json  pyproject.toml
reports  src  uv.lock

Using CPython 3.13.5 interpreter at: …
Creating virtual environment at: .venv
Resolved 11 packages in 0.79ms
Installed 10 packages in 571ms
 + numpy==2.5.4
 + pandas==3.1.0
 + scikit-learn==1.9.1
 + scipy==1.18.1
 … আরও ৬টি, সব প্রথম কম্পিউটারের মতো

$ sha256sum data/raw/orders.csv
6dc23919dc729ae61dda11755c48e3ff
a8ff94c4e480051bb4d56cf0ac03243f
 *data/raw/orders.csv

$ uv run python src/train.py
data sha256: 6dc23919dc72
metrics    : {'accuracy': 0.83, 'f1': 0.8}

$ git diff --exit-code reports/metrics.json \
    && echo "metrics.json: no difference"
metrics.json: no difference

খেয়াল করুন, এখানে “একই কম্পিউটারের আরেকটি ফোল্ডার” ব্যবহার হয়েছে, আলাদা operating system নয়। অন্য OS-এ বা অন্য CPU-তে দশমিকের চতুর্থ ঘরে কদাচিৎ পার্থক্য আসতে পারে (অংশ ৩-এর সতর্কতা)। তাই অনেক দল metrics তুলনায় একটি ছোট সহনশীলতা (tolerance) রাখে, যেমন পার্থক্য ০.০০০১-এর কম হলে “মিলেছে”।

৯ · যেভাবে পুনরুৎপাদন ভাঙে — seed ছাড়া split আর না-বাঁধা library

এবার উল্টো পরীক্ষা: চারটি উপাদানের একটি ইচ্ছা করে ভাঙা। Clone করা ফোল্ডারে train.py-এর একটি শব্দ বদলানো হলো। সত্যিকারের run:

$ git diff src/train.py
…
 X_tr, X_te, y_tr, y_te = train_test_split(
-    X, y, test_size=params["test_size"], random_state=params["seed"], stratify=y)
+    X, y, test_size=params["test_size"], random_state=None, stratify=y)
$ for i in 1 2 3; do uv run python src/train.py | tail -1; done
metrics    : {'accuracy': 0.87, 'f1': 0.8506}
metrics    : {'accuracy': 0.87, 'f1': 0.8434}
metrics    : {'accuracy': 0.84, 'f1': 0.8095}
$ git diff reports/metrics.json
…
 {
-  "accuracy": 0.83,
-  "f1": 0.8
+  "accuracy": 0.84,
+  "f1": 0.8095

একই code (প্রায়), একই ডেটা, একই environment — তবু তিনবারে তিন রকম F1. random_state=None মানে scikit-learn প্রতিবার operating system থেকে নতুন এলোমেলোতা নেয়, তাই কোন ১০০টি অর্ডার test-এ যাবে তা প্রতিবার আলাদা। ভয়ের দিকটি খেয়াল করুন: তিনটি ফলই “ভালো” দেখাচ্ছে, কোনো error নেই, কোনো warning নেই। ০.৮৭ দেখে কেউ বলতে পারতেন “model উন্নত হয়েছে!” — আসলে শুধু সহজ অর্ডারগুলো test-এ পড়েছে।

নিচের কোডে পাতার ভেতরেই একই ঘটনা দেখুন। একই seed-এর ডেটা, একই model; প্রথম সারিতে split-এর seed 42, দ্বিতীয় সারিতে seed নেই। scikit-learn প্রথমবার লোড হতে প্রায় ১০ সেকেন্ড লাগতে পারে।

import numpy as np
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split

rng = np.random.default_rng(42)              # the data itself is seeded
n = 400
dist = rng.uniform(1, 20, n).round(1)
items = rng.integers(1, 6, n)
rain = rng.uniform(0, 60, n).round(1)
score = 0.3 * dist + 0.06 * rain + 0.2 * items + rng.normal(0, 1.2, n)
X = np.column_stack([dist, items, rain])
y = (score > 6).astype(int)

def run(split_seed):
    X_tr, X_te, y_tr, y_te = train_test_split(
        X, y, test_size=0.25, random_state=split_seed, stratify=y)
    model = LogisticRegression(max_iter=1000).fit(X_tr, y_tr)
    return round(model.score(X_te, y_te), 2)

print("random_state=42  :", [run(42) for _ in range(5)])
print("random_state=None:", [run(None) for _ in range(5)])

random_state=42  : [0.83, 0.83, 0.83, 0.83, 0.83]
random_state=None: [0.85, 0.91, 0.9, 0.8, 0.85]

ওঠানামা কতটা স্বাভাবিক — একটি হিসাব

Seed ছাড়া প্রকল্পের তিনটি run-এ এলো ০.৮৪ থেকে ০.৮৭, আর পাতার কোডের একটি run-এ ০.৮০ থেকে ০.৯১। এটি কি বড় পার্থক্য? Test set-এ n = ১০০টি অর্ডার, আর আসল accuracy p ধরা যাক ০.৮৩. প্রতিটি অর্ডার ঠিক বা ভুল — একটি মুদ্রা-নিক্ষেপের মতো। তখন মাপা accuracy-র standard error (SE, অর্থাৎ বারবার নতুন test set নিলে সংখ্যাটি গড়ে কতটা ওঠানামা করে):

SE = √(p(1 − p) / n) = √(0.83 × 0.17 / 100) = √0.001411 ≈ 0.038

মোটামুটি নিয়ম হলো, ফল ±২ SE-র মধ্যে, অর্থাৎ ০.৮৩ ± ০.০৭৫ (প্রায় ০.৭৫৫ থেকে ০.৯০৫) পর্যন্ত, স্বাভাবিক ওঠানামা। প্রকল্পের তিনটি সংখ্যাই এই সীমার ভেতরে। পাতার run-এর ০.৯১ সীমার সামান্য বাইরে, যা অস্বাভাবিক নয়: ±২ SE-র বাইরে পড়ার সম্ভাবনা মোটামুটি ৫%, তাই অনেকগুলো split নিলে মাঝে মাঝে এমন হবেই। (হিসাবটি আনুমানিক; এখানে সব split একই ৪০০ সারি থেকে নেওয়া।) তাই সিদ্ধান্ত দুটি: (ক) ১০০ সারির test set-এ ০.০১–০.০৪-এর পার্থক্য দেখে “উন্নতি” দাবি করা যায় না; (খ) seed বেঁধে রাখলে অন্তত একই test set-এ তুলনা হয়, কিন্তু seed বেঁধে একটি ভাগ্যবান seed বেছে নেওয়াও এক ধরনের প্রতারণা। সৎ পথ হলো কয়েকটি seed বা cross-validation-এ গড় আর বিস্তার দেখানো, যা পরের মডিউলগুলোতে আসবে।

না-বাঁধা library — নীরব বদল

দ্বিতীয় বড় ফাঁদ হলো version না বাঁধা। pip install scikit-learn লিখলে আজ যা আসে, ছয় মাস পরে তা আসবে না। নতুন version-এ কোনো default বদলাতে পারে, যেমন একটি model-এর ডিফল্ট solver বা iteration সংখ্যা, আর তাতে একই code-এর ফল বদলায়, কোনো error ছাড়াই। scikit-learn-এর ইতিহাসে এমন default বদল একাধিকবার হয়েছে, আর তারা সাধারণত আগে থেকে FutureWarning দিয়ে সতর্ক করে; এই কারণেই warning উপেক্ষা করা বিপজ্জনক। এই পর্বের নিজের উদাহরণেও দেখলেন: পাতার Pyodide আর প্রকল্পের environment-এ scikit-learn-এর version আলাদা, আর কোন version-এ ফলটি এসেছে তা log-এ লেখা না থাকলে পরে পার্থক্যের কারণ খুঁজে পাওয়া কঠিন। প্রতিকার আপনি জানেন: uv.lock, uv sync --locked, আর log-এ sklearn version.

১০ · AI-এর যুগে পুনরুৎপাদনযোগ্য কাজ

AI সহকারী একটি পুরো training script বা প্রকল্পের কাঠামো কয়েক সেকেন্ডে লিখে দিতে পারে। কিন্তু reproducibility-র দিক থেকে তার লেখা code-এ কিছু ভুল প্রায়ই দেখা যায়। নিচের তালিকা সাধারণ অভিজ্ঞতা থেকে, কোনো জরিপ থেকে নয়।

AI-এর দেওয়া প্রকল্প হাতে পেলে — যাচাইয়ের চেকলিস্ট

• Script দুবার চালিয়েছি, আর metrics.json দুবারই হুবহু এক
• প্রতিটি random কাজে (ডেটা তৈরি, split, model) seed আছে, আর seed এসেছে একটি জায়গা থেকে (params.json)
• uv.lock commit করা আছে, আর নতুন ফোল্ডারে uv sync --locked সফল
• ডেটার hash log-এ আছে, আর raw ফোল্ডারের কোনো ফাইল code হাতে বদলায় না
• Split সবকিছুর আগে; metrics শুধু test set-এ; একটি সরল baseline-এর সঙ্গে তুলনা আছে
• git status-এ .env, বড় ডেটা, model ফাইল বা ব্যক্তিগত ডেটা নেই; notebook-এর output মোছা
• ব্যবহৃত প্রতিটি ফাংশন আমার version-এর official docs-এ খুঁজে পেয়েছি; কোনো warning চাপা দেওয়া হয়নি
• সম্পূর্ণ নতুন একটি clone-এ পুরো পথ (sync → hash → train → diff) একবার চালিয়ে দেখেছি