Módulo 3.1 — Instalar o kernel

🐍 Python 3.10+ — Requisito base

AIOS exige Python ≥ 3.10. Versões 3.11 e 3.12 funcionam e oferecem performance ~10% melhor. Versões antigas (3.8/3.9) quebram imports do Cerebrum por causa de syntax features (match-case, type hints novos, dataclasses).

# Verificar versão
$ python3 --version
Python 3.11.7

# Se < 3.10, instale via pyenv
$ curl https://pyenv.run | bash
$ pyenv install 3.11.7
$ pyenv global 3.11.7

💡 Dica

Em macOS, evite o Python do sistema. Use pyenv ou brew. Em Linux, use o do package manager ou pyenv. Em Windows, prefira WSL2 — o suporte nativo é mais sofrido.

📥 Clonar AIOS + Cerebrum

Em Local Kernel mode, mantenha os dois repos lado a lado. Instalar AIOS já puxa Cerebrum como dependência, mas ter o clone local facilita ler código, debugar e contribuir.

$ mkdir -p ~/projects/aios-stack && cd ~/projects/aios-stack
$ git clone https://github.com/agiresearch/AIOS.git
$ git clone https://github.com/agiresearch/Cerebrum.git
$ ls
AIOS  Cerebrum

📊 Por que dois clones

Debugar o kernel exige ler código do AIOS
Customizar uma syscall exige ler código do Cerebrum
Editable install (pip install -e .) pega mudanças sem reinstalar
Atualizar é git pull, não pip install --upgrade

⚡ CPU vs CUDA — Dois requirements distintos

AIOS distribui dois arquivos de dependência. CPU (requirements.txt) é leve, ideal se você só vai chamar APIs externas. CUDA (requirements-cuda.txt) traz torch+vLLM para hospedar modelos locais — pesado, exige GPU NVIDIA.

CPU — Quando escolher

✓Você só usa APIs (OpenAI, Claude, Gemini)
✓Notebook sem GPU
✓Servidor VPS barato
✓~500MB de deps

CUDA — Quando escolher

✓Vai hospedar modelo via vLLM
✓Pesquisa com dados sensíveis (sem cloud)
✓GPU NVIDIA com CUDA 11+
✓~5GB de deps

$ cd AIOS
# CPU:
$ pip install -r requirements.txt
# OU GPU:
$ pip install -r requirements-cuda.txt

📦 Virtualenv / conda — Isolamento obrigatório

AIOS tem dezenas de dependências transitivas (vLLM, torch, pydantic, transformers, openai, anthropic, etc). Instalar no Python global é receita para conflito. Sempre crie ambiente isolado.

# Opção 1: venv (padrão)
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

# Opção 2: conda
$ conda create -n aios python=3.11
$ conda activate aios
$ pip install -r requirements.txt

# Opção 3: uv (mais rápido)
$ uv venv && source .venv/bin/activate
$ uv pip install -r requirements.txt

💡 uv é gostoso

uv (Astral) é 10-100x mais rápido que pip e funciona como drop-in. Vale a pena para projetos AIOS por causa do volume de deps.

✅ Verificar instalação — Smoke test

Antes de configurar keys e brincar com Terminal UI, valide que imports funcionam. Smoke test simples evita "instalei tudo e nada responde" — pega problema cedo.

$ python -c "import aios; print('AIOS OK')"
AIOS OK
$ python -c "import cerebrum; print('Cerebrum OK')"
Cerebrum OK

# Se quiser checar a versão Rust experimental
$ cd AIOS/aios-rs && cargo check
# (deve compilar sem erro)

📊 Se falhar

ModuleNotFoundError: aios → venv não ativada ou install incompleto
ImportError: cannot import name X → versão de pydantic conflitante
OSError: cuda libs → instalou requirements-cuda sem GPU
SyntaxError: match → Python < 3.10

🐛 Troubleshooting comum

Os 5 erros mais frequentes durante setup. Conhecê-los economiza ~80% do tempo de instalação para todo mundo que vem depois de você.

Sintoma	Causa	Fix
torch CUDA mismatch	CUDA toolkit ≠ versão torch	Reinstale torch com index URL correto
gcc missing	Sem build-essential	`sudo apt install build-essential`
pydantic v1 vs v2	Lib antiga forçando v1	`pip install pydantic>=2`
config.yaml not found	Path errado	Crie em `aios/config/config.yaml`
port already in use	Outro kernel rodando	`pkill -f aios.kernel`

💡 Estratégia

Se travar >30 min em setup, mate a venv e recomece do zero com uv em Python 3.11. Investir 15 min refazendo é mais barato que 2h debugando.

✅ Resumo do Módulo

✓

Python ≥ 3.10. 3.11/3.12 são as melhores escolhas.

✓

Dois repos: AIOS + Cerebrum. Lado a lado, facilita debug.

✓

CPU se for usar APIs, CUDA se for hospedar. Não confunda.

✓

Venv ou conda sempre. Nunca instale no Python global.

✓

Smoke test antes de configurar. Pega problema cedo.

Próximo módulo:

3.2 — 🔑 Configurar providers. config.yaml, keys, kernel up e Terminal UI.

← Voltar para Trilha Próximo: 3.2 →