Laborator practic: clasificare și rutare sigură în Python

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git jq tree

python3 --version
git --version
jq --version
tree --version

mkdir -p ~/ai-agents-zero-to-expert
cd ~/ai-agents-zero-to-expert

mkdir -p \
  src \
  tests \
  data \
  docs/lessons \
  docs/architecture-decisions \
  configs \
  skills \
  evaluations \
  logs

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

git config --global init.defaultBranch main
git init

cat > .gitignore <<'EOF'
.venv/
__pycache__/
*.py[cod]
.env
.env.*
logs/*
!logs/.gitkeep
.DS_Store
EOF

touch logs/.gitkeep

tree -a -L 2

cat > src/classification_game.py <<'PY'
#!/usr/bin/env python3
"""Jocul de clasificare din Lectia 1.

Jocul arata ca etichetele se suprapun. Un sistem poate fi ML + workflow +
automat fara sa fie agent.
"""

from __future__ import annotations

import argparse
import random
from dataclasses import dataclass

VALID_TAGS = {"ALG", "ML", "GEN", "FLOW", "AGENT", "AUTO"}


@dataclass(frozen=True)
class Scenario:
    name: str
    description: str
    tags: frozenset[str]
    explanation: str


SCENARIOS = [
    Scenario(
        "Calculator",
        "Evalueaza 17 x 43.",
        frozenset({"ALG"}),
        "Un algoritm determinist transforma intrarea intr-o iesire exacta.",
    ),
    Scenario(
        "Backup nocturn",
        "Un job cron copiaza un folder pe alt disc in fiecare noapte.",
        frozenset({"ALG", "FLOW", "AUTO"}),
        "Este un workflow automat fix. Actioneaza fara aprobare imediata, dar nu este machine learning.",
    ),
    Scenario(
        "Rutarea spamului",
        "Un model invatat prezice spamul, iar sistemul de e-mail muta mesajul automat.",
        frozenset({"ALG", "ML", "FLOW", "AUTO"}),
        "Predictia este invatata, iar mutarea in folder o face o regula determinista.",
    ),
    Scenario(
        "Poezie dintr-o singura cerere",
        "Un model lingvistic scrie o poezie dintr-un singur prompt.",
        frozenset({"ML", "GEN"}),
        "Este inferenta generativa, dar nu exista o bucla cu instrumente, orientata spre un obiectiv.",
    ),
    Scenario(
        "Arbore de raspunsuri FAQ",
        "Un bot de suport urmeaza un arbore de decizie stabilit dinainte.",
        frozenset({"ALG", "FLOW"}),
        "Este automatizare conversationala, nu neaparat AI si nu un agent.",
    ),
    Scenario(
        "Investigator de facturi",
        "Sistemul interogheaza inregistrari, alege alta verificare cand lipsesc dovezi, redacteaza un mesaj si asteapta aprobarea.",
        frozenset({"ALG", "ML", "GEN", "FLOW", "AGENT"}),
        "Alege dinamic actiunile, dar nu trimite singur mesajul in exterior.",
    ),
    Scenario(
        "Aspirator robotic",
        "Cartografiaza camerele si schimba traseul cand intalneste un obstacol.",
        frozenset({"ALG", "ML", "AGENT", "AUTO"}),
        "Percepe si actioneaza intr-o bucla cu feedback. Implementarile pot folosi si reguli, si modele invatate.",
    ),
    Scenario(
        "Robot de sudura cu traseu fix",
        "Repeta acelasi traseu de sudura programat.",
        frozenset({"ALG", "FLOW", "AUTO"}),
        "Automatizarea fizica nu inseamna automat un agent adaptiv.",
    ),
    Scenario(
        "Motor clasic de sah",
        "Cauta mutarile posibile cu o logica de evaluare scrisa de oameni.",
        frozenset({"ALG", "AGENT"}),
        "Alege actiuni catre un obiectiv, fara sa aiba nevoie de machine learning.",
    ),
    Scenario(
        "Pipeline RAG de raspuns",
        "Recupereaza pasaje din documente si produce un raspuns cu citari, intr-o secventa fixa.",
        frozenset({"ALG", "ML", "GEN", "FLOW"}),
        "Un RAG obisnuit este de regula un pipeline. Devine agentic daca sistemul planifica si repeta cautarea in timpul rularii.",
    ),
    Scenario(
        "Asistent de cod",
        "Sugereaza cod, dar nu poate modifica fisiere si nu poate rula comenzi.",
        frozenset({"ML", "GEN"}),
        "Este un asistent, nu un agent care actioneaza.",
    ),
    Scenario(
        "Agent de programare",
        "Planifica modificari, editeaza fisiere, ruleaza teste, observa erorile si incearca din nou.",
        frozenset({"ALG", "ML", "GEN", "AGENT", "AUTO"}),
        "Are o bucla cu instrumente, orientata spre obiectiv, si modifica mediul.",
    ),
]


def parse_tags(raw: str) -> set[str]:
    """Transforma textul scris de utilizator in etichete valide, normalizate."""
    normalized = raw.upper().replace(",", " ").split()
    return {tag for tag in normalized if tag in VALID_TAGS}


def score_tags(expected: set[str] | frozenset[str], actual: set[str]) -> float:
    """Intoarce un scor de suprapunere, intre 0 si 1, care iarta greselile partiale."""
    union = set(expected) | actual
    if not union:
        return 1.0
    return len(set(expected) & actual) / len(union)


def print_reference() -> None:
    print("\nEtichete:")
    print("  ALG   comportamentul vine din reguli si calcule scrise de oameni")
    print("  ML    in sistem exista un model invatat din exemple")
    print("  GEN   produce continut nou")
    print("  FLOW  urmeaza un flux automat stabilit dinainte")
    print("  AGENT isi alege singur actiunile pentru un obiectiv")
    print("  AUTO  actioneaza fara aprobarea imediata a unui om")


def run_game(rounds: int, seed: int | None) -> None:
    rng = random.Random(seed)
    selected = SCENARIOS.copy()
    rng.shuffle(selected)
    selected = selected[: min(rounds, len(selected))]

    total = 0.0
    print("\nCE FEL DE SISTEM ESTE?")
    print("Scrie toate etichetele potrivite, separate prin spatii sau virgule.")
    print_reference()

    for index, scenario in enumerate(selected, start=1):
        print(f"\n[{index}/{len(selected)}] {scenario.name}")
        print(scenario.description)
        try:
            answer = input("Etichetele tale: ")
        except (EOFError, KeyboardInterrupt):
            print("\nJoc intrerupt. Nu s-a salvat nimic.")
            return
        actual = parse_tags(answer)
        round_score = score_tags(scenario.tags, actual)
        total += round_score

        expected = ", ".join(sorted(scenario.tags))
        print(f"Raspunsul cursului: {expected}")
        print(f"Explicatie: {scenario.explanation}")
        print(f"Scor runda: {round_score:.0%}")

    percentage = 100 * total / len(selected)
    print(f"\nScor final: {percentage:.1f}%")
    if percentage >= 85:
        print("Excelent: separi corect capabilitatile, controlul si autoritatea.")
    elif percentage >= 65:
        print("Inceput bun: reciteste diferenta dintre workflow, agent si autonomie.")
    else:
        print("Reia jocul dupa ce revezi harta celor trei axe.")


def list_scenarios() -> None:
    print_reference()
    for scenario in SCENARIOS:
        tags = ", ".join(sorted(scenario.tags))
        print(f"\n{scenario.name} [{tags}]\n  {scenario.description}\n  {scenario.explanation}")


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--rounds", type=int, default=8)
    parser.add_argument("--seed", type=int)
    parser.add_argument("--list", action="store_true")
    args = parser.parse_args()

    if args.rounds < 1:
        parser.error("--rounds trebuie sa fie cel putin 1")

    if args.list:
        list_scenarios()
    else:
        run_game(args.rounds, args.seed)


if __name__ == "__main__":
    main()
PY

chmod +x src/classification_game.py

python src/classification_game.py

python src/classification_game.py --rounds 12 --seed 42

./src/classification_game.py --list

cat > tests/test_classification_game.py <<'PY'
import sys
import unittest
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "src"))

from classification_game import parse_tags, score_tags


class ClassificationGameTests(unittest.TestCase):
    def test_parse_tags_accepts_commas_spaces_and_case(self):
        self.assertEqual(parse_tags("ml, gen agent"), {"ML", "GEN", "AGENT"})

    def test_parse_tags_ignores_unknown_values(self):
        self.assertEqual(parse_tags("ML MAGIC FLOW"), {"ML", "FLOW"})

    def test_exact_score(self):
        self.assertEqual(score_tags({"ML", "GEN"}, {"ML", "GEN"}), 1.0)

    def test_partial_score(self):
        self.assertAlmostEqual(score_tags({"ML", "GEN"}, {"ML"}), 0.5)


if __name__ == "__main__":
    unittest.main()
PY

python -m unittest discover -s tests -v

cat > src/task_router.py <<'PY'
#!/usr/bin/env python3
"""Un baseline determinist de rutare.

Clasifica o sarcina dupa reguli explicite si intoarce pasul urmator stabilit dinainte.
Nu are model invatat, nu are plan adaptiv, nu are instrumente si nu are bucla de actiune.
"""

from __future__ import annotations

import json
import sys
from dataclasses import asdict, dataclass


@dataclass(frozen=True)
class RouteDecision:
    route: str
    reason: str
    requires_human: bool


HIGH_IMPACT_KEYWORDS = {"send", "delete", "publish", "pay"}

ROUTES = [
    ({"calculate", "sum", "multiply", "total"}, "calculation", "Aritmetica exacta se face in cod determinist.", False),
    ({"summarize", "rewrite", "draft"}, "language-task", "Transformarea de limbaj poate folosi mai tarziu un model generativ.", True),
    ({"classify", "detect", "predict"}, "prediction-task", "Predictia poate folosi mai tarziu reguli sau machine learning.", True),
]


def route_task(task: str) -> RouteDecision:
    words = {word.strip(".,!?;:").lower() for word in task.split()}

    # Precedenta de siguranta: regulile de interdictie sau de aprobare sunt evaluate
    # inaintea rutelor obisnuite. Altfel, o cerere precum "calculate and pay the invoice"
    # s-ar potrivi intai cu "calculate" si ar ocoli gresit aprobarea umana.
    if words & HIGH_IMPACT_KEYWORDS:
        return RouteDecision(
            "high-impact-action",
            "Actiunile externe sau distructive cer aprobare explicita.",
            True,
        )

    for keywords, route, reason, requires_human in ROUTES:
        if words & keywords:
            return RouteDecision(route, reason, requires_human)

    return RouteDecision(
        "manual-review",
        "Nicio regula determinista nu se potriveste sigur cu aceasta sarcina.",
        True,
    )


def main() -> None:
    task = " ".join(sys.argv[1:]).strip()
    if not task:
        task = input("Descrie o sarcina: ").strip()
    if not task:
        raise SystemExit("Este nevoie de o sarcina, nu de un text gol.")

    decision = route_task(task)
    print(json.dumps(asdict(decision), indent=2))


if __name__ == "__main__":
    main()
PY

chmod +x src/task_router.py

python src/task_router.py "calculate the invoice total"
python src/task_router.py "draft a polite reminder"
python src/task_router.py "delete the original files"
python src/task_router.py "investigate what happened"

python src/task_router.py "calculate and pay the invoice" | jq .requires_human

cat > tests/test_task_router.py <<'PY'
import sys
import unittest
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "src"))

from task_router import route_task


class TaskRouterTests(unittest.TestCase):
    def test_calculation_is_low_risk_by_itself(self):
        result = route_task("calculate the invoice total")
        self.assertEqual(result.route, "calculation")
        self.assertFalse(result.requires_human)

    def test_high_impact_rule_overrides_calculation(self):
        result = route_task("calculate and pay the invoice")
        self.assertEqual(result.route, "high-impact-action")
        self.assertTrue(result.requires_human)

    def test_unknown_task_goes_to_manual_review(self):
        result = route_task("investigate what happened")
        self.assertEqual(result.route, "manual-review")
        self.assertTrue(result.requires_human)


if __name__ == "__main__":
    unittest.main()
PY

python -m unittest discover -s tests -v

cat > docs/agent-profile.md <<'EOF'
# Profilul agentului meu

## Nume provizoriu

`[Alege un nume temporar]`

## Utilizatorul vizat

`[Cine îl va folosi?]`

## Rezultatul dorit

`[Ce trebuie să devină mai ușor, rapid, sigur sau exact?]`

## Domeniu

`[Documente, cercetare, operațiuni, programare, media, știință etc.]`

## Informații pe care le-ar putea citi

- `[Sursa 1]`
- `[Sursa 2]`

## Acțiuni pe care le-ar putea pregăti

- `[Acțiunea 1]`
- `[Acțiunea 2]`

## Acțiuni executabile automat

- `[Începe doar cu acțiuni reversibile și cu risc redus]`

## Acțiuni care cer aprobare umană

- ștergere;
- plată;
- publicare;
- mesaje trimise extern;
- modificări ale înregistrărilor sensibile;
- `[Adaugă acțiuni specifice domeniului]`.

## Nivel inițial de autonomie

**Nivelul 1 — doar consultativ.**

## Dovezi de succes

`[Cum vei măsura că agentul a ajutat?]`

## Riscuri cunoscute

- răspunsuri nesusținute;
- permisiuni excesive;
- expunerea datelor private;
- selectarea greșită a instrumentului;
- `[Riscuri specifice proiectului]`.
EOF

cat > docs/architecture-decisions/ADR-0001-start-with-a-deterministic-baseline.md <<'EOF'
# ADR-0001: Începem cu un baseline determinist

## Stare

Acceptată

## Context

Proiectul va deveni treptat un agent AI. Dacă am începe direct cu un LLM, ar fi greu să separăm comportamentul modelului de comportamentul orchestrării.

## Decizie

Construim și testăm un router determinist înainte de a conecta un model.

## Consecințe

- Avem un baseline transparent.
- Putem măsura dacă AI aduce îmbunătățire reală.
- Regulile de siguranță rămân deterministe.
- Prima versiune are flexibilitate lingvistică redusă.
EOF

cat > docs/lessons/lesson-01.md <<'EOF'
# Fișa Lecției 1

## Concepte pe care le pot explica

- [ ] AI versus automatizare
- [ ] machine learning versus AI generativă
- [ ] model versus agent
- [ ] workflow versus agent
- [ ] agentic versus autonom
- [ ] clasificarea pe cele trei axe

## Cel mai dificil caz-limită

`[Scrie exemplul și motivul.]`

## Un pas al agentului meu care trebuie să folosească reguli

`[Răspuns]`

## Un pas care ar putea necesita model învățat

`[Răspuns]`

## O acțiune care trebuie aprobată

`[Răspuns]`
EOF

git config --global user.name "Numele tău"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

git add .
git status
git commit -m "Complete lesson 1 system classification lab"

python src/classification_game.py --rounds 12

git status --ignored

source ~/ai-agents-zero-to-expert/.venv/bin/activate

sudo apt install --reinstall python3-venv

chmod +x src/classification_game.py src/task_router.py

python src/classification_game.py

cd ~/ai-agents-zero-to-expert
python -m unittest discover -s tests -v