docs/core-python.md

# Core Python dokumentācija

## Pārskats

core-python ir Maris AI MI kodols, kurā notiek visa AI apstrāde.

## Struktūra

```
maris_core/
├── text/       # Teksta ģenerēšana (Qwen3)
├── images/     # Attēlu ģenerēšana (Stable Diffusion)
├── audio/      # STT (Whisper), TTS, MusicGen
├── video/      # Video ģenerēšana (CogVideoX)
├── code/       # Koda ģenerēšana (Qwen3-Coder)
├── autonomous/ # Autonomais aģents
├── training/   # Modeļa apmācība
├── data/       # Datu apstrāde
└── utils/      # HF integrācija, logging
```

## Galvenais modelis

```python
from transformers import pipeline

pipe = pipeline(
    "text-generation",
    model="Maris Core Reasoning",
    device_map="auto",
)
```

## Orchestrācijas slānis

core-python tagad satur arī master-model orchestration slāni:

- `/v1/orchestrator/system` — atgriež galvenā modeļa un visu atzaru topoloģiju;
- `/v1/orchestrator/route` — nosaka, uz kuru atzaru konkrēts pieprasījums būtu jāroutē;
- `text/generate` pieņem `profile`, lai viens galvenais modelis varētu strādāt
  kā vispārīgs assistants, coder vai planner bez atsevišķa frontend hardcode.

Routing tagad izmanto:

1. **LLM-based router**, kas mēģina izvēlēties capability no definētā branch kataloga;
2. **safe heuristic fallback**, ja LLM nav pieejams vai nevar atgriezt derīgu JSON lēmumu.

## API endpoints

Visi endpoints ir pieejami caur FastAPI `/docs` Swagger UI.

Papildus:

- `/health` — liveness/servisa pieejamība;
- `/ready` — rāda, vai galvenais teksta modelis ir pilnībā uzsilis. Ja modelis vēl
  ielādējas vai ir retry cooldown režīmā pēc neveiksmīgas ielādes, endpoint atgriezīs
  `503` ar detalizētu `text_model.state`, `text_model.model`,
  `text_model.compatibility_restore_active` un, ja vajag, `text_model.last_error`.

## Runtime HF compatibility restore

Teksta runtime loaderis tagad izmanto to pašu `maris_hf_compatible_path(...)`
mehānismu, ko training/export plūsma. Tas nozīmē:

- ja snapshotā ir `maris-compatibility.json`, runtime startup laikā tiek atjaunoti
  oriģinālie HF loader lauki (`config.json`, `tokenizer_config.json`,
  `adapter_config.json`);
- tas strādā gan ar lokālu modeļa direktoriju, gan ar remote Hugging Face repo;
- remote snapshot restore ieslēdz ar:

```bash
MARIS_RUNTIME_COMPAT_ALLOW_REMOTE_SNAPSHOT=true
```

Ja izmanto citu aliasu vai vēlies saglabāt backward-compatibility ar vecāku
konfigurāciju, der arī:

```bash
MARIS_HF_COMPAT_ALLOW_REMOTE_SNAPSHOT=true
HF_RUNTIME_COMPAT_ALLOW_REMOTE_SNAPSHOT=true
```

Šis ir īpaši svarīgi Railway izvietojumam, kur modelis bieži tiek ielādēts tieši
no Hub repozitorija, nevis no lokāla persistent storage ceļa.

## Maris publicēšanas integrācija

Katru reizi kad Maris AI ģenerē saturu, tas automātiski tiek saglabāts:

```python
from maris_core.utils.hf_integration import HFIntegration

hf = HFIntegration()
await hf.save_conversation("Ko tu māki?", "Es māku...")
await hf.save_generation("image", "saulriets jūrā", {...})
```

## Testēšana

```bash
cd core-python
pytest tests/ -v
```

Ja validē tieši runtime loader/compatibility restore:

```bash
cd /home/runner/work/Maris-MI/Maris-MI/core-python
pytest tests/test_training_hf_compat.py tests/test_text.py -v
```

## Fine-tuning entrypoint

Profesionalam Transformers fine-tuning flow izmanto:

```bash
bash ./huggingface/train.sh
```

Šis entrypoint izmanto JSON konfigurāciju no `huggingface/training-config.json` Maris publicēšanas pipeline vajadzībām
un saglabā rezultātus `core-python/output/model/`.

Papildus trenēšanas konfigurācijā tagad ir arī:

- `branch_name` — kuram atzaram skrējiens paredzēts;
- `branch_focus` — kādu specializāciju branch trenē;
- `adapter_type` — piemēram, `full` vai `lora`.

Ja vēlies palaist visu branch suite:

```bash
cd core-python
python scripts/train_model.py --config ../huggingface/training-config.json --all-branches
```

Tas:

- izveido atsevišķus output direktorijus katram atzaram;
- trenē tekstā balstītos branch (`master`, `coder`, `planner`);
- multimodālajiem specialist branch saglabā manifestus ar branch-specific konfigurāciju un iemeslu, kāpēc tiem vajadzīgs cits treniņa pipeline.