🐍 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ãopip 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 incompletoImportError: cannot import name X→ versão de pydantic conflitanteOSError: cuda libs→ instalou requirements-cuda sem GPUSyntaxError: 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
Próximo módulo:
3.2 — 🔑 Configurar providers. config.yaml, keys, kernel up e Terminal UI.