better ba1

<!-- langtabs-end -->

````

### Code examples

**Run every code block before publishing it.** Reading it is not enough: code that looks right

often fails, or runs and teaches the wrong thing.

- **Run the page's blocks in order**, in a clean environment with current library versions. The

  blocks of a page share variables top to bottom, as a reader would run them. A block that

  depends on an earlier one says so in a comment or in the text just before.

- **Use real data that ships with the library** (`load_digits`, `load_breast_cancer`,

  `load_diabetes`, a Gymnasium environment) instead of undefined variables or random tensors.

  The result should mean something: an untrained model or random data teaches nothing.

- **Show the real output.** When a comment or an `text` block shows a result, it is the one the

  code produced. Set seeds (`random_state=42`, `torch.manual_seed(42)`) so it is reproducible.

- **Follow industry practice, kept simple**: split before fitting, fit scalers on the training

  set only (a `Pipeline` does this), `stratify` classification splits, evaluate on data the model

  has not seen, `model.eval()` and `torch.no_grad()` for inference. Avoid deprecated APIs.

- **Pseudocode is marked as such** (` ```text `), never as `python`.

- If something can't be run (it needs a GPU, an API key or a private dataset), say so in the text

  and run the parts that can be.

## Mathematical content

### Formulas (MathJax)

- **Example before abstraction**: ground a concept in a concrete instance before naming it.

- Inside a single list, choose infinitive or imperative and keep it uniform.

### Folded blocks

`<details>` blocks are **extensions**, not containers for content the page needs:

- **The page must read correctly with every block closed.** If a later paragraph, formula or code

  block depends on something, that something is visible. A block can deepen an idea; it never

  carries the idea itself.

- **Add one whenever it's worth expanding an idea**: a derivation, the formula behind an idea

  already explained in words, a longer code variant, an edge case. Don't fold a sentence or two:

  if it's that short, either it belongs in the text or it isn't needed.

- **One coherent topic per block**, named by its `<summary>`: `La fórmula`, `Per què la

  sigmoide?`, `K-fold amb una xarxa neuronal (PyTorch)`. Formulas inside still get their symbol

  list and an "En paraules senzilles" line.

- **Place it right after the idea it extends**, in the same section.

- **Never put a Plotly container inside one.** Plotly sizes a hidden container wrong. Figures stay

  in the visible flow.

The markup needs blank lines around the inner Markdown, or it isn't rendered:

```markdown

<details>

<summary>La fórmula</summary>

\\\[

...

\\\]

</details>

```

## Working rules

- **Stay scoped to the file you were asked to edit.** Do not restructure neighbouring pages,

## Before finishing

- `mdbook build` completes without errors.

- Every code block on the edited pages has been run, and any output shown matches what it produced.

- The page starts with `# Títol` followed by `<!-- toc -->`.

- New pages are listed in `src/SUMMARY.md`.

- If a top-level section changed, `src/llms.txt` and the Content map reflect it.

## Not registered in `SUMMARY.md`

These Markdown files exist under `src/` but are not listed in `src/SUMMARY.md`. mdBook therefore

does not build them and they are not reachable on the site — `apunts.jg5.dev/<ruta>.html` returns

404 for each.

does not build them and they are not reachable on the site: `apunts.jg5.dev/<ruta>.html` returns

404.

| File | Lines | Title | Last commit |

| --- | ---: | --- | --- |

| `src/apren/ba1/ml_reasoning.md` | 34 | Sistemes Basats en Coneixement i Raonament | 2025-09-29 |

| `src/apren/ba1/ml_regression.md` | 78 | Funcions de regressió en Aprenentatge Automàtic | 2025-09-29 |

| `src/apren/ba1/ml_reinforcement.md` | 964 | Aprenentatge per reforç | 2025-09-29 |

| `src/m9/uf1c/ssl_socols.md` | 103 | Comunicació SSL amb sòcols | 2023-11-11 |

For each one, decide between:

Decide between:

- **Publish** — add an entry to `src/SUMMARY.md` at the right nesting depth and run

  `./scripts/gen-sitemap.sh`. Natural placement by path:

  - `apren/ba1/*` → under *Aprenentatge Automàtic* (`apren/ba1.md`)

  - `m9/uf1c/ssl_socols.md` → under *Criptografia* (`m9/uf1c.md`)

- **Drop** — delete the file.

The sitemap no longer needs a decision of its own: it is generated from `SUMMARY.md`, so these four

The sitemap no longer needs a decision of its own: it is generated from `SUMMARY.md`, so drafts

are already absent from it and will appear the moment they are registered.

Notes:

- `ml_reinforcement.md` (964 lines) is past the ~800-line threshold in `AGENTS.md`; if published,

  consider splitting it into subpages.

- `ml_reasoning.md` (34 lines) and `ml_regression.md` (78 lines) look unfinished rather than merely

  unregistered.

- `ssl_socols.md` has not been touched since 2023 and may be superseded by the current

  *Criptografia* and *Sòcols i serveis* pages.

## Resolved

- `src/apren/ba1/ml_reinforcement.md`: rewritten, split in two (`ml_reinforcement.md` and

  `ml_reinforcement_deep.md`) and published under *Aprenentatge Automàtic → Ampliació*.

- `src/apren/ba1/ml_regression.md`: dropped. Feature transformations (log, square root) and

  "start simple, look at the errors" moved to `ml_supervised.md`.

- `src/apren/ba1/ml_reasoning.md`: dropped. Its glossary moved to `apren/basics/ml_dictionary.md`

  as *IA simbòlica i raonament*.

## Why drafts used to leak into the sitemap

`src/sitemap.xml` was produced by `mdbook-sitemap-generator`, which walks the `src/` filesystem,

.pissarra-tanca:hover {

  opacity: 1;

}

/* Els blocs plegables mostren que es poden clicar */

details > summary {

  cursor: pointer;

}

  - [Introducció a la IA](./apren/ml_ia.md)

  - [Aprenentatge Automàtic](./apren/ba1.md)

    - [Aprenentatge supervisat](./apren/ba1/ml_supervised.md)

    - [Mètriques d'avaluació](./apren/ba1/ml_metrics.md)

    - [Classificació](./apren/ba1/ml_classification.md)

    - [Xarxes neuronals](./apren/ba1/ml_neuralnets.md)

    - [Embeddings i cerca vectorial](./apren/ba1/ml_embeddings_vectorsearch.md)

    - [Guia d'aplicació i diagnòstic](./apren/ba1/ml_advice.md)

    - [Arbres de decisió](./apren/ba1/ml_decisiontrees.md)

    - [K-veïns més propers](./apren/ba1/ml_knn.md)

    - [Aprenentatge no supervisat](./apren/ba1/ml_unsupervised.md)

    - [Avaluació de models](./apren/ba1/ml_evaluation.md)

    - [Ampliació](./apren/ba1/ampliacio.md)

      - [Xarxes neuronals: ampliació](./apren/ba1/ml_neuralnets_ampliacio.md)

      - [Aprenentatge no supervisat: ampliació](./apren/ba1/ml_unsupervised_ampliacio.md)

      - [K-veïns més propers](./apren/ba1/ml_knn.md)

      - [Recomanadors](./apren/ba1/ml_recommender.md)

      - [Aprenentatge per reforç](./apren/ba1/ml_reinforcement.md)

      - [Aprenentatge per reforç profund](./apren/ba1/ml_reinforcement_deep.md)

  - [LLMs i IA Generativa](./apren/llms.md)

    - [Transformers i Models de Llenguatge](./apren/llms/ml_transformers.md)

    - [LLM vs. ML tradicional](./apren/llms/llm_vs_ml.md)

  - *El desenvolupador decideix* quin patró seguir (repositori, servei, pipeline...) i per què encaixa al projecte.

  - *La IA implementa* el codi que aplica aquell patró de manera consistent.

- **Fronteres entre mòduls**

  - *El desenvolupador decideix* on acaba un mòdul i on comença un altre, quines responsabilitats té cadascun. Per a tipologies de fronteres i mecanismes de separació, vegeu [Arquitectura i fronteres](../fonaments/disseny.md#arquitectura-i-fronteres).

  - *El desenvolupador decideix* on acaba un mòdul i on comença un altre, quines responsabilitats té cadascun. Per a tipologies de fronteres i mecanismes de separació, consulta [Arquitectura i fronteres](../fonaments/arquitectura.md#arquitectura-i-fronteres).

  - *La IA implementa* els imports, les connexions internes i el cablejat entre mòduls.

- **Interfícies públiques**

  - *El desenvolupador decideix* les signatures, els tipus de retorn i el contracte d'errors de cada funció exposada.