AI কোডে পরিচ্ছন্নতা — function, type hint, ছোট test আর seed

১ · “চলেছে, তাই ঠিক” — ডেটার কাজের সবচেয়ে বড় ফাঁদ

সাধারণ প্রোগ্রামে ভুল করলে প্রায়ই সঙ্গে সঙ্গে টের পাওয়া যায়। Login পাতা খোলে না, বোতাম কাজ করে না, প্রোগ্রাম লাল error দেখিয়ে থেমে যায়। ডেটার কাজে ব্যাপারটা আলাদা। ভুল কোডও দিব্যি চলে, একটি সুন্দর সংখ্যা বা চার্ট দেয় — শুধু সংখ্যাটা ভুল। একে বলে silent bug বা নীরব বাগ।

বাজারঘরের (এই কোর্সের কাল্পনিক অনলাইন দোকান) ডেটায় এমন ভুল কোথায় কোথায় ঢুকতে পারে, তার কয়েকটি পরিচিত রূপ:

চতুর্থ সারির সমস্যাটির নাম data leakage — উত্তরের তথ্য কোনো ফাঁক দিয়ে input-এ ঢুকে পড়া। পর্ব ০৫-এ (AI কোন সমস্যা সমাধান করে) এর পরিচয় পেয়েছেন, আর পর্ব ৫৬-এ train, validation, test ভাগ করার সময় এটি বিস্তারিত আসবে। এই পর্বের প্রশ্ন অন্য: কোন অভ্যাস থাকলে এমন ভুল আগেই ধরা পড়ে?

নিচের ছবিতে বাজারঘরের একটি সাধারণ কাজের ধারা। প্রতিটি ধাপে কোন নীরব বাগ ঢোকে, আর কোন অভ্যাস তাকে আটকায় — এই পর্বের বাকি অংশ এই ছবিরই বিস্তার।

এবার একটি নীরব বাগ নিজের চোখে দেখুন। বাজারঘরের ৪ দিনের বিক্রি ৩টি জেলায় (হাজার টাকায়) একটি টেবিলে রাখা — সারি মানে দিন, কলাম মানে জেলা, অর্থাৎ shape (4, 3). লক্ষ্য: প্রতিটি জেলার গড় বিক্রি। NumPy-তে axis=0 মানে “সারিগুলো জুড়ে নিচের দিকে”, ফলে প্রতি কলামে একটি গড়; axis=1 মানে প্রতি সারিতে একটি গড়। Axis-এর পুরো ব্যাখ্যা পর্ব ১৬-এ আসবে।

import numpy as np

# rows = 4 days, columns = 3 districts (sales in thousand taka)
sales = np.array([[12, 30, 7],
                  [14, 28, 9],
                  [11, 35, 6],
                  [13, 31, 8]])
districts = ["Dhaka", "Ctg", "Rajshahi"]
print("sales.shape =", sales.shape)

def mean_per_district(s, axis):
    out = s.mean(axis=axis)
    assert out.shape == (s.shape[1],), f"expected ({s.shape[1]},), got {out.shape}"
    return out

wrong = sales.mean(axis=1)               # silent bug: averages each DAY
print("no guard, axis=1:", np.round(wrong, 2))   # 4 numbers, looks fine!

try:
    mean_per_district(sales, axis=1)
except AssertionError as e:
    print("guard caught it -> AssertionError:", e)

right = mean_per_district(sales, axis=0)
for d, m in zip(districts, right):
    print(f"{d:9s} mean = {m:.2f}")

sales.shape = (4, 3)
no guard, axis=1: [16.33 17.   17.33 17.33]
guard caught it -> AssertionError: expected (3,), got (4,)
Dhaka     mean = 12.50
Ctg       mean = 31.00
Rajshahi  mean = 7.50

একই ঘটনা ধাপে ধাপে দেখুন। প্রতিটি ধাপে সবুজ লাইনটি চলছে, আর ডান দিকে মানগুলো বদলাচ্ছে।

1sales = np.array(rows)2m = sales.mean(axis=AXIS)3assert m.shape == (3,), m.shape4report(m)

২ · Notebook cell থেকে ছোট pure function

Jupyter notebook-এ (পর্ব ০৮-এ বিস্তারিত) কাজ শুরু করা খুব আরামের: একটি cell লিখুন, চালান, ফল দেখুন। সমস্যা শুরু হয় যখন cell-এর সংখ্যা পঞ্চাশ ছাড়ায়। কোন cell কোন ক্রমে চলেছিল, কোন variable কোথায় বদলেছে — মনে থাকে না। একে বলে hidden state: notebook-এর স্মৃতিতে এমন অবস্থা জমে থাকে, যা পাতায় লেখা কোড পড়ে বোঝা যায় না।

প্রতিকার হলো বারবার ব্যবহারের কাজগুলোকে ছোট pure function-এ তুলে আনা। Pure function দুটি শর্ত মানে: (১) একই input দিলে সবসময় একই output দেয়; (২) বাইরের কিছু বদলায় না — কোনো global variable, কোনো ফাইল, input DataFrame-টিও নয়। বাইরের কিছু বদলানোকে বলে side effect. Python-এ function-এর সাধারণ নিয়ম আর default argument-এর ফাঁদ Python কোর্সের function পর্বে আছে; এখানে শুধু ডেটার দিকটি দেখি।

নিচের stepper-এ একটি অতি পরিচিত notebook-বাগ: যে cell একটি column-কে “নিজের জায়গায়” বদলায়, তাকে ভুল করে দুবার চালালে কী হয়।

df["price"] = df["price"] / 100
df["price"].iloc[0]
→ 1250.0   # ছিল 125000 পয়সা

df["price"] = df["price"] / 100
df["price"].iloc[0]
→ 12.5   # আবার ১০০ দিয়ে ভাগ!

input : orders (price_paisa কলামসহ)
output: নতুন DataFrame, price_taka কলামসহ
বদলাবে না: orders নিজে

def add_taka(orders: pd.DataFrame) -> pd.DataFrame:
    out = orders.copy()
    out["price_taka"] = out["price_paisa"] / 100
    return out

add_taka(orders)["price_taka"].iloc[0]  → 1250.0
add_taka(orders)["price_taka"].iloc[0]  → 1250.0
orders["price_paisa"].iloc[0]           → 125000

কোন কাজকে function বানাবেন? একটি সহজ নিয়ম: যে কোড দুবার copy-paste করেছেন, যে কোডের ফল অন্য কোড ব্যবহার করে, আর যে কোড ভুল হলে টাকার হিসাব ভুল হয় — এগুলো function হবে। Notebook-এ থাকুক শুধু ডাকা আর দেখা: clean = clean_orders(raw), তারপর একটি চার্ট।

• এক function, এক কাজ: “লোড করো, পরিষ্কার করো, model চালাও, চার্ট আঁকো” একটি function-এ নয়।
• ফাইল path, column-এর নাম, হার — argument হিসেবে: function-এর ভেতরে লুকানো না রেখে।
• ছবি আঁকা আর print আলাদা: হিসাবের function সংখ্যা বা টেবিল ফেরত দেবে, দেখানোর কাজ ডাকার জায়গায়।
• Randomness থাকলে seed বা generator argument হিসেবে — অংশ ৬-এ দেখবেন।

৩ · Type hint — ডেটার কোডে কী লিখবেন, mypy কী ধরে

Type hint হলো কোডে লেখা একটি ঘোষণা: “এই argument একটি int, এই function একটি DataFrame ফেরত দেয়।” Python নিজে চালানোর সময় এগুলো যাচাই করে না — এগুলো মানুষের জন্য আর static type checker-এর জন্য, যেমন mypy বা pyright. এরা কোড না চালিয়েই পড়ে দেখে, ঘোষণার সঙ্গে ব্যবহার মিলছে কি না। Type hint-এর পূর্ণ ব্যাকরণ (list[int], Optional, generic) Python কোর্সের type hint পর্বে আছে।

ডেটার কোডে কয়েকটি কাজের রূপ:

এবার সত্যিকারের run. একটি ছোট ফাইলে ইচ্ছে করে চারটি ভুল রাখা হলো, আর একটি জিনিস রাখা হলো যা ভুল হলেও mypy ধরতে পারবে না।

import numpy as np
import pandas as pd
from numpy.typing import NDArray


def paisa_to_taka(paisa: int) -> int:
    return paisa / 100


def district_mean(prices: NDArray[np.float64]) -> NDArray[np.float64]:
    return prices.mean(axis=0)


def find_district(code: str, table: dict[str, str]) -> str | None:
    return table.get(code)


def clean_orders(df: pd.DataFrame) -> pd.DataFrame:
    return df.dropna(subset=["price"])


orders = pd.DataFrame({"price": [120.0, None, 80.0]})
name = find_district("DHK", {"DHK": "Dhaka"})
print(name.upper())
print(clean_orders(orders["price"]))
print(paisa_to_taka("12500"))

সত্যিকারের run (লেখার সময়ে Python 3.13.5, mypy 2.4.1, numpy 2.5.4, pandas 3.1.0, pandas-stubs সহ):

~/bazarghar-ai$ mypy --version
mypy 2.4.1 (compiled: yes)
~/bazarghar-ai$ mypy typed_bugs.py
typed_bugs.py:7: error: Incompatible return value type (got "float", expected "int")  [return-value]
typed_bugs.py:24: error: Item "None" of "str | None" has no attribute "upper"  [union-attr]
typed_bugs.py:25: error: Argument 1 to "clean_orders" has incompatible type "Series[Any]"; expected "DataFrame"  [arg-type]
typed_bugs.py:26: error: Argument 1 to "paisa_to_taka" has incompatible type "str"; expected "int"  [arg-type]
Found 4 errors in 1 file (checked 1 source file)

দুটি ব্যবহারিক কথা। এক, সব library type তথ্য দেয় না। একই প্রকল্পে scikit-learn import করা ফাইলে mypy বলেছিল: Skipping analyzing "sklearn.linear_model": module is installed, but missing library stubs or py.typed marker. সমাধান হিসেবে pyproject.toml-এ ওই module-এর জন্য ignore_missing_imports = true লেখা হয়েছে, তারপর Success: no issues found in 2 source files এসেছে (সত্যিকারের run). এর মানে sklearn-এর ব্যবহার mypy যাচাই করছে না — এটুকু মেনে নিয়েই কাজ। দুই, pyright (VS Code-এর Pylance-এর ভেতরেও এটি) একই ধরনের কাজ করে, কিছু নিয়মে আলাদা আচরণ করে; এখানে চালানো হয়নি।

Static checker কোড চালায় না। কিন্তু ডেটা আসে চলার সময় — CSV, API, ব্যবহারকারী। তাই সীমান্তে একটি runtime যাচাইও দরকার। নিচের কোডে একটি payment API পয়সায় টাকা পাঠায়। NewType দিয়ে “Paisa” নামের একটি আলাদা type ঘোষণা করা হলো, যাতে mypy ভুল মিশ্রণ ধরতে পারে; আর একটি সীমা-যাচাই চলার সময় অবাস্তব গড় থামায়।

from typing import NewType

Paisa = NewType("Paisa", int)        # a label for type checkers only

def paisa_to_taka(p: Paisa) -> float:
    return p / 100

def average_order_taka(amounts_taka: list[float]) -> float:
    avg = sum(amounts_taka) / len(amounts_taka)
    if not 10 <= avg <= 50_000:       # runtime guard: plausible taka range
        raise ValueError(f"average {avg:,.0f} taka is not plausible; "
                         "paisa passed as taka?")
    return avg

shop = [1250.0, 980.0, 1475.5]                          # already taka
gateway = [Paisa(125000), Paisa(98000), Paisa(147550)]  # payment API: paisa

p = Paisa(125000)
print("Paisa(125000) at runtime:", p, type(p).__name__)
print("shop average:", round(average_order_taka(shop), 2))
taka = [paisa_to_taka(x) for x in gateway]
print("converted   :", round(average_order_taka(taka), 2))
try:
    average_order_taka(gateway)      # mypy would flag this; Python does not
except ValueError as e:
    print("runtime guard ->", e)

Paisa(125000) at runtime: 125000 int
shop average: 1235.17
converted   : 1235.17
runtime guard -> average 123,517 taka is not plausible; paisa passed as taka?

৪ · Assertion — সস্তা কিন্তু সজাগ পাহারাদার

Assertion হলো কোডের মাঝখানে লেখা একটি দাবি: “এখানে এই কথা অবশ্যই সত্য।” Python-এ assert শর্ত, "বার্তা" লিখলে শর্ত মিথ্যা হলে সঙ্গে সঙ্গে AssertionError ওঠে। ডাক্তার যেমন অপারেশনের আগে রোগীর নাম আর কোন পাশে অপারেশন — দুটো আবার মিলিয়ে নেন, assertion তেমনই একটি ছোট, সস্তা মিলিয়ে নেওয়া।

ডেটার কোডে কোন দাবিগুলো সবচেয়ে কাজের:

বড় প্রকল্পে টেবিলের প্রতিটি column-এর নিয়ম (type, সীমা, null চলবে কি না) একটি “schema” হিসেবে লিখে রাখার জন্য তৃতীয় পক্ষের library-ও আছে, যেমন pandera. শুরুতে কয়েকটি সাধারণ assert-ই যথেষ্ট; প্রয়োজন বাড়লে তখন ভাবুন।

৫ · ছোট test — জানা ডেটায় জানা উত্তর

Assertion চলে আসল ডেটার সঙ্গে, প্রতিবার। Unit test চলে আলাদা করে, একটি ছোট, হাতে বানানো ডেটায়, যার সঠিক উত্তর আপনি আগে থেকেই জানেন। পরীক্ষার খাতা দেখার আগে শিক্ষক যেমন একটি “উত্তরমালা” বানিয়ে রাখেন, test তেমন উত্তরমালা। Testing-এর তত্ত্ব — কী test করবেন, কতটুকু — Software Engineering কোর্সের unit testing পর্বে আছে, আর pytest-এর পূর্ণ ব্যবহার Python কোর্সের pytest পর্বে।

Test runner আসলে কী করে, তা বুঝতে প্রথমে নিজের হাতে একটি খুদে runner লিখি। এটি pytest নয়, তার একটি শেখার মডেল: প্রতিটি test function চালানো, AssertionError বা অন্য error এলে FAIL লেখা, না এলে PASS. পরীক্ষার বিষয় একটি দাম-পরিষ্কারের function — “৳1,250” বা “১২৫০ টাকা” থেকে সংখ্যা বের করা, আর ফাঁকা হলে None.

def clean_price(text):
    """'৳1,250' -> 1250.0 ; empty text -> None"""
    t = text.replace("৳", "").replace(",", "").replace("টাকা", "").strip()
    return float(t)

def test_symbol_and_comma():
    assert clean_price("৳1,250") == 1250.0

def test_bangla_digits():
    assert clean_price("১২৫০ টাকা") == 1250.0

def test_empty_is_none():
    assert clean_price("  ") is None

def run_tests(tests):
    passed = 0
    for t in tests:
        try:
            t()
            print("PASS", t.__name__)
            passed += 1
        except AssertionError:
            print("FAIL", t.__name__, "-> assertion was false")
        except Exception as e:
            print("FAIL", t.__name__, "->", type(e).__name__ + ":", e)
    print(f"{passed} passed, {len(tests) - passed} failed")

run_tests([test_symbol_and_comma, test_bangla_digits, test_empty_is_none])

PASS test_symbol_and_comma
PASS test_bangla_digits
FAIL test_empty_is_none -> ValueError: could not convert string to float: ''
2 passed, 1 failed

আসল pytest — একটি ছোট নির্দিষ্ট dataset আর একটি property

এবার আসল pytest. বাজারঘরের clean_orders function তিনটি কাজ করে: দাম না থাকা সারি বাদ দেয়, পয়সাকে টাকায় নেয়, জেলার নামের space ছাঁটে। Test-এ একটি তিন সারির খুদে টেবিল আছে, যেটি একটি fixture হিসেবে লেখা — pytest প্রতিটি test-কে এই টেবিলের নতুন কপি দেয়। শেষ test-টি অন্য ধরনের: নির্দিষ্ট উদাহরণ নয়, একটি সাধারণ নিয়ম — “পরিষ্কারের পর মোট টাকা × ১০০ = মোট পয়সা”, আর Hypothesis নামের library শত শত এলোমেলো তালিকা বানিয়ে নিয়মটি যাচাই করে। একে বলে property-based testing.

import pandas as pd
import pytest
from hypothesis import given
from hypothesis import strategies as st

from cleaning import clean_orders


@pytest.fixture
def tiny_orders() -> pd.DataFrame:
    return pd.DataFrame({
        "district": [" dhaka", "Sylhet ", "khulna"],
        "price_paisa": [12550, None, 8000],
    })


def test_drops_missing_price(tiny_orders):
    out = clean_orders(tiny_orders)
    assert len(out) == 2


def test_paisa_becomes_taka(tiny_orders):
    out = clean_orders(tiny_orders)
    assert out["price_taka"].tolist() == [125.5, 80.0]


def test_district_names_cleaned(tiny_orders):
    out = clean_orders(tiny_orders)
    assert out["district"].tolist() == ["Dhaka", "Khulna"]


@given(st.lists(st.integers(min_value=0, max_value=10_000_000), min_size=1))
def test_total_is_preserved(paisa):
    df = pd.DataFrame({"district": ["x"] * len(paisa), "price_paisa": paisa})
    out = clean_orders(df)
    assert out["price_taka"].sum() * 100 == pytest.approx(sum(paisa))

clean_orders-এর প্রথম সংস্করণে টাকায় নেওয়ার লাইন ছিল out["price_paisa"] // 100 — // মানে ভাগ করে নিচের পূর্ণসংখ্যা। সত্যিকারের run (pytest 9.2.0, Hypothesis 6.170.14):

~/bazarghar-ai$ pytest -q
.F.F                                                                     [100%]
================================== FAILURES ===================================
___________________________ test_paisa_becomes_taka ___________________________
…
>       assert out["price_taka"].tolist() == [125.5, 80.0]
E       assert [125.0, 80.0] == [125.5, 80.0]
E
E         At index 0 diff: 125.0 != 125.5
…
___________________________ test_total_is_preserved ___________________________
…
paisa = [1]
…
>       assert out["price_taka"].sum() * 100 == pytest.approx(sum(paisa))
E       assert np.int64(0) == 1 ± 1.0e-06
…
E       Failing test case: test_total_is_preserved(
E           paisa=[1],
E       )
…
=========================== short test summary info ===========================
FAILED test_cleaning.py::test_paisa_becomes_taka - assert [125.0, 80.0] == [1...
FAILED test_cleaning.py::test_total_is_preserved - assert np.int64(0) == 1 ± ...
2 failed, 2 passed in 2.07s

~/bazarghar-ai$ pytest -q
....                                                                     [100%]
4 passed in 0.58s

ডেটার function-এর জন্য কোন test লিখবেন? কয়েকটি ধরন প্রায় সবসময় কাজে লাগে: (১) তিন-চার সারির হাতে বানানো টেবিলে হাতে হিসাব করা উত্তর; (২) কিনারার ঘটনা — ফাঁকা টেবিল, সব null, একটিমাত্র সারি, বাংলা ও ইংরেজি মেশানো নাম; (৩) property — মোট টাকা ঠিক থাকে, সারি কখনো বাড়ে না, ফল সবসময় ০ থেকে ১-এর মধ্যে; (৪) আগে ধরা পড়া প্রতিটি বাগের জন্য একটি test, যাতে সে আর ফিরে না আসে।

৬ · Randomness আর reproducibility — seed-এর কাজ ও সীমা

AI-এর কাজে randomness সবখানে: ডেটা এলোমেলো করে train আর test ভাগ, model-এর শুরুর ওজন, নমুনা বাছাই। কম্পিউটারের “random” সংখ্যা আসলে একটি হিসাবের সূত্র থেকে আসে — একে বলে pseudo-random number generator (PRNG). সূত্রটি একটি শুরুর সংখ্যা থেকে চলে; সেই সংখ্যাই seed. একই seed দিলে একই ধারা আসে। এর ফলে আপনার ফল অন্য কেউ (বা ছয় মাস পরের আপনি) হুবহু আবার পেতে পারেন — একে বলে reproducibility.

নিচের কোডে চারটি জিনিস একসঙ্গে: একই seed-এ দুই run, seed ছাড়া দুই run, একই generator দুবার ডাকা, আর Python-এর random ও NumPy-র পুরোনো global পদ্ধতি।

import random
import numpy as np

def sample(seed=None):
    rng = np.random.default_rng(seed)
    return rng.integers(100, 1000, size=5)   # 5 order ids

print("seed 42, run 1:", sample(42))
print("seed 42, run 2:", sample(42))
a, b = sample(), sample()
print("no seed, two runs equal?", np.array_equal(a, b))

rng = np.random.default_rng(7)
print("same rng, 1st call:", rng.integers(1, 7, size=4))
print("same rng, 2nd call:", rng.integers(1, 7, size=4))

random.seed(42)
print("random.seed(42):", [random.randint(1, 6) for _ in range(4)])
np.random.seed(42)                       # old global way
print("legacy np.random.seed(42):", np.random.randint(100, 1000, size=5))

seed 42, run 1: [180 796 689 494 489]
seed 42, run 2: [180 796 689 494 489]
no seed, two runs equal? False
same rng, 1st call: [6 4 5 6]
same rng, 2nd call: [4 5 6 2]
random.seed(42): [6, 1, 1, 6]
legacy np.random.seed(42): [202 535 960 370 206]

কোনটি ব্যবহার করবেন

• NumPy: নতুন কোডে rng = np.random.default_rng(seed) বানিয়ে সেই rng function-এ argument হিসেবে পাঠান। পুরোনো np.random.seed() পুরো প্রোগ্রামের একটি global অবস্থা বদলায় — কোনো library-র ভেতরের একটি ডাক সেই ধারা থেকে সংখ্যা খেয়ে ফেললে আপনার পরের সংখ্যাগুলো বদলে যায়, অথচ কোডে কিছু বদলায়নি। NumPy-র docs-ও নতুন কোডে Generator ব্যবহারের পরামর্শ দেয়। Ruff-এর NPY নিয়ম এটি ধরে (সত্যিকারের run): NPY002 Replace legacy `np.random.seed` call with `np.random.Generator`.
• Python-এর random: random.seed(42) চলে, তবে আলাদা উদ্দেশ্যে আলাদা random.Random(42) object রাখা আরও পরিষ্কার।
• scikit-learn: যেখানে randomness আছে (train_test_split, অনেক model), সেখানে random_state=42 দিন। একটি int দিলে প্রতিবার একই ফল; None দিলে প্রতিবার আলাদা।

আরেকটি সতর্কতা: seed দিয়ে একটি ভালো ফল “বেছে নেওয়া” প্রতারণার কাছাকাছি। ৪২ দিয়ে accuracy ০.৮৮, ৭ দিয়ে ০.৮১ — তাহলে ৪২-ই লিখব? না। সৎ পথ হলো কয়েকটি seed-এ চালিয়ে গড় আর ছড়ানো (spread) দুটোই জানানো। Seed ফল পুনরুৎপাদনের জন্য, ফল সাজানোর জন্য নয়।

৭ · লম্বা কাজে logging, আর সব সেটিং এক জায়গায়

পাঁচ মিনিটের কাজে print চলে। কিন্তু model training যখন রাতভর চলে, তখন সকালে প্রশ্ন আসে: কখন শুরু হয়েছিল? কোন সেটিং-এ? কোথায় সতর্কবার্তা এসেছিল? Logging প্রতিটি বার্তার সঙ্গে সময়, গুরুত্বের মাত্রা (DEBUG, INFO, WARNING, ERROR) আর উৎসের নাম রাখে, আর এক লাইনে ঠিক করা যায় কোন মাত্রা দেখাবে বা ফাইলে লিখবে। Python-এর logging module-এর বিস্তারিত Python কোর্সের debugging ও logging পর্বে আছে।

দ্বিতীয় অভ্যাস: configuration এক জায়গায়। Seed, ডেটার আকার, test-এর ভাগ, threshold — কোডের বিশ জায়গায় ছড়ানো “জাদুর সংখ্যা” থাকলে একটি বদলাতে গিয়ে আরেকটি ভুলে যান। একটি @dataclass (dataclass পর্ব) সব সেটিং এক জায়গায় রাখে, আর frozen=True দিলে মাঝপথে কেউ বদলাতে পারে না। সবচেয়ে বড় সুবিধা: log-এর প্রথম লাইনেই পুরো config ছাপা হয়, ফলে প্রতিটি ফলের পাশে তার সেটিং লেখা থাকে।

"""Toy late-delivery model for Bazarghar: config in one place, logging, seeds."""

import logging
from dataclasses import dataclass

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

log = logging.getLogger("bazarghar.train")


@dataclass(frozen=True)
class Config:
    seed: int = 42
    n_orders: int = 2000
    test_size: float = 0.25
    late_score: float = 5.0


def make_orders(cfg: Config) -> tuple[np.ndarray, np.ndarray]:
    rng = np.random.default_rng(cfg.seed)
    dist_km = rng.uniform(1, 20, cfg.n_orders)
    rain_mm = rng.uniform(0, 60, cfg.n_orders)
    score = 0.3 * dist_km + 0.08 * rain_mm + rng.normal(0, 1, cfg.n_orders)
    X = np.column_stack([dist_km, rain_mm])
    y = (score > cfg.late_score).astype(int)
    assert X.shape == (cfg.n_orders, 2), X.shape
    assert not np.isnan(X).any(), "NaN in features"
    return X, y


def main(cfg: Config) -> None:
    log.info("config %s", cfg)
    X, y = make_orders(cfg)
    log.info("orders=%d late_rate=%.3f", len(y), y.mean())
    X_tr, X_te, y_tr, y_te = train_test_split(
        X, y, test_size=cfg.test_size, random_state=cfg.seed, stratify=y
    )
    model = LogisticRegression().fit(X_tr, y_tr)
    log.info("test accuracy=%.3f", model.score(X_te, y_te))
    if model.score(X_te, y_te) < 0.7:
        log.warning("accuracy below 0.7, check the data")


if __name__ == "__main__":
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
    )
    main(Config())

সত্যিকারের run, পরপর দুবার (scikit-learn 1.9.1, numpy 2.5.4, Python 3.13.5):

~/bazarghar-ai$ python train.py
2026-11-04 19:20:15,726 INFO    bazarghar.train: config Config(seed=42, n_orders=2000, test_size=0.25, late_score=5.0)
2026-11-04 19:20:15,726 INFO    bazarghar.train: orders=2000 late_rate=0.580
2026-11-04 19:20:15,741 INFO    bazarghar.train: test accuracy=0.882
~/bazarghar-ai$ python train.py
2026-11-04 19:20:16,744 INFO    bazarghar.train: config Config(seed=42, n_orders=2000, test_size=0.25, late_score=5.0)
2026-11-04 19:20:16,744 INFO    bazarghar.train: orders=2000 late_rate=0.580
2026-11-04 19:20:16,753 INFO    bazarghar.train: test accuracy=0.882

Config-এর মান কোথা থেকে আসবে — কোডে default, একটি config.toml ফাইল, নাকি command line — প্রকল্পভেদে আলাদা। নিয়ম একটাই: একটি উৎস, একবার পড়া, log-এ ছাপা। আর গোপন তথ্য (যেমন API key) কখনো config ফাইলে বা কোডে নয়; পরিবেশ বা আলাদা গোপন ভাণ্ডার থেকে, আর উদাহরণে শুধু example-secret এর মতো স্পষ্ট নকল মান।

৮ · Ruff — lint আর format এক টুলে

Linter কোড চালায় না, পড়ে — আর সন্দেহজনক ধাঁচ খোঁজে: ব্যবহার না হওয়া import, == None, সব error গিলে ফেলা except:, mutable default argument. Formatter কোডের চেহারা (ফাঁকা লাইন, space, লাইনের দৈর্ঘ্য) একটি নির্দিষ্ট নিয়মে সাজায়, যাতে review-এ চেহারা নিয়ে তর্ক না হয়। Ruff (Astral নামের প্রতিষ্ঠানের, Rust-এ লেখা, ২০২২ সাল থেকে) দুটোই করে, আর খুব দ্রুত। Flake8, isort, Black-এর মতো পুরোনো টুলের অনেক নিয়ম এতে আছে; আবার অনেক দল এখনো সেই পুরোনো টুলগুলোই ব্যবহার করে — দুটোই চলে।

নিচের ফাইলটি notebook থেকে তাড়াহুড়োয় তুলে আনা কোডের মতো:

import os
import numpy as np
import pandas as pd

def load(path, cols=[]):
    df = pd.read_csv(path)
    for c in cols:
        if df[c].isna().sum() == None:
            print(f"no missing")
    try:
        df["price"] = df["price"].astype(float)
    except:
        pass
    return df

def summarise(df):
    l = df["price"].mean()
    return l

pyproject.toml-এ নিয়মের দল বেছে দেওয়া হয়েছে: select = ["E", "F", "B", "I", "NPY", "PD"] — pycodestyle, Pyflakes, bugbear, import সাজানো, NumPy আর pandas-এর নিয়ম। সত্যিকারের run (ruff 0.17.3):

~/bazarghar-ai$ ruff check --output-format concise messy.py
messy.py:1:1: I001 [*] Import block is un-sorted or un-formatted
messy.py:1:8: F401 [*] `os` imported but unused
messy.py:2:17: F401 [*] `numpy` imported but unused
messy.py:5:21: B006 Do not use mutable data structures for argument defaults
messy.py:8:34: E711 Comparison to `None` should be `cond is None`
messy.py:9:19: F541 [*] f-string without any placeholders
messy.py:12:5: E722 Do not use bare `except`
messy.py:17:5: E741 Ambiguous variable name: `l`
Found 8 errors.
[*] 4 fixable with `--fix` (2 unsafe fixes available with `--fix --unsafe-fixes`).
~/bazarghar-ai$ ruff format --diff messy.py
--- messy.py
+++ messy.py
@@ -2,6 +2,7 @@
 import numpy as np
 import pandas as pd

+
 def load(path, cols=[]):
…
1 file would be reformatted

অভ্যাস হিসেবে: কোড commit করার আগে ruff check আর ruff format, আর editor-এ Ruff-এর extension চালু রাখুন, যাতে লেখার সময়েই দাগ পড়ে। Lint সবুজ মানে কোড ঠিক — তা নয়; lint ধরে পরিচিত ধাঁচের ভুল, যুক্তির ভুল নয়। সেজন্য test আর review.

৯ · AI কোড review — একটি চেকলিস্ট

Code review মানে কোড মূল ধারায় মেলানোর আগে আরেকজন (বা আপনি নিজে, এক দিন পরে) পড়ে দেখা। সাধারণ review-এর নিয়ম — ছোট পরিবর্তন, সম্মানজনক মন্তব্য — Software Engineering কোর্সের code review পর্বে আছে। ডেটা ও AI কোডে বাড়তি কিছু প্রশ্ন জিজ্ঞেস করতে হয়, কারণ এখানকার বাগ নীরব। পাঠযোগ্য কোডের সাধারণ নীতি দেখতে পারেন clean code পর্বে।

ডেটা ও AI কোড review-এর চেকলিস্ট

• প্রতিটি column-এর নাম আর unit স্পষ্ট (price_taka, dist_km) — শুধু price বা d নয়
• Join, filter বা groupby-এর আগে-পরে সারির সংখ্যা যাচাই হয়েছে; array-র shape-এ assert আছে
• Null, ডুপ্লিকেট আর মানের সীমা যাচাই হয়েছে; খালি except দিয়ে error গেলা হয়নি
• Feature-এ এমন কিছু নেই, যা আন্দাজের সময় জানা থাকবে না (label ফাঁস); split সবার আগে
• হিসাবের কাজ ছোট pure function-এ; মূল DataFrame জায়গায় বদলানো হয়নি
• গুরুত্বপূর্ণ function-এর জন্য ছোট জানা-ডেটার test আর কিনারার ঘটনার test আছে, আর তা পাস করছে
• সব randomness-এ seed বা random_state; seed config থেকে আসে, আর library-র version লেখা আছে
• Seed, threshold, path — সব config-এ; log-এ config আর মূল সংখ্যাগুলো ছাপা হয়
• Type hint আছে, mypy বা pyright পরিষ্কার; Ruff check ও format পরিষ্কার
• Metric test ডেটায়, একটি সহজ baseline-এর পাশে; একটি সংখ্যা হাতে মিলিয়ে দেখা হয়েছে

১০ · AI-এর যুগে — AI সহকারীর লেখা ডেটা-কোড যাচাই

AI সহকারী দিয়ে cleaning function বা training script লেখানো আজ খুব সাধারণ। সমস্যা হলো, AI-এর লেখা কোডও প্রথমবারেই চলে — আর এই পর্বের মূল কথা, চলা মানেই ঠিক নয়। AI সহকারী প্রায়ই যে ভুলগুলো করে:

AI সহকারীর উত্তর হাতে পেলে — যাচাইয়ের চেকলিস্ট

• কোড নিজে চালিয়েছি; ফলের shape আর কয়েকটি নমুনা সারি দেখে মিলিয়েছি
• mypy আর ruff check চালিয়েছি; প্রতিটি বার্তা পড়েছি, চাপা দিইনি
• AI-এর লেখা test-এর প্রত্যাশিত মান নিজে হাতে হিসাব করে মিলিয়েছি — কোডের আউটপুট কপি করে test বানানো হয়নি
• ইচ্ছে করে একটি বাগ ঢুকিয়ে দেখেছি test সত্যিই ব্যর্থ হয় কি না
• প্রতিটি function ও parameter আমার version-এর অফিসিয়াল docs-এ আছে কি না দেখেছি
• Split সবার আগে; metric test ডেটায় আর baseline-এর পাশে
• কোনো গ্রাহকের নাম, ফোন নম্বর, ঠিকানা বা আসল ডেটা AI chatbot-এ পেস্ট করিনি