✦ AXIOM — Agente con Propósito Autónomo

Guía de instalación para macOS

Un agente de IA que nace sin identidad y la construye solo. Corre completamente en local en tu Mac — sin nube, sin suscripciones.

---

Requisitos

Requisito	Versión mínima	Notas
macOS	13 Ventura	Funciona en 12 Monterey
Python	3.11+	python3 --version
Ollama	última	ollama.com
Homebrew	cualquiera	brew.sh
RAM	8 GB	16 GB recomendado

---

Instalación (10 minutos)

1. Dependencias del sistema

# Homebrew (si no lo tienes)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Audio: portaudio para grabación desde CLI, ffmpeg para conversión
brew install portaudio ffmpeg

2. Entorno Python

cd axiom/
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Para grabación de micrófono en CLI
pip install sounddevice soundfile

3. Ollama y modelo

# Instalar Ollama desde ollama.com o:
brew install ollama

# Terminal 1: servidor
ollama serve

# Terminal 2: descargar modelo
ollama pull llama3.2          # 2GB, recomendado
# ollama pull mistral          # 4GB, más capaz
# ollama pull gemma2:2b        # 1.6GB, para Macs con 8GB RAM

4. Arrancar

source .venv/bin/activate
python main.py                 # http://localhost:8000

---

Modos de uso

python main.py              # Servidor web + API REST
python main.py cli          # Terminal interactivo
python main.py telegram     # Bot de Telegram
python main.py all          # Web + Telegram (instancia compartida)

---

Configuración (config.yaml)

model:
  name: llama3.2
  temperature: 0.75

agent:
  name: AXIOM
  reflection_every_n_turns: 4   # Cada cuántas respuestas reflexiona sobre su SOUL

voice:
  stt:
    enabled: true
    model: "base"                # tiny|base|small|medium|large-v3
    language: null               # null=autodetect, "es"=español forzado
  tts:
    enabled: true
    backend: "auto"              # auto → 'say' en macOS (local, sin internet)
    macos_voice: "Paulina"       # say -v ? para ver voces disponibles
    edge_voice: "es-VE-SebastianNeural"

telegram:
  token: ""
  owner_chat_id: 0
  allowed_users: []

Configuración desde UI (recomendado)

En la app web/desktop abre ⚙ Setup y configura:

• Modelo local de Ollama (selector dinámico)
• Provider externo + API key opcional
• Telegram (token/chat_id/allowed users)
• Ajustes de contexto/timeout/autónomo

En macOS, las claves sensibles se guardan en Keychain cuando es posible.

---

Voces macOS (TTS local, sin internet)

# Ver todas las voces instaladas:
say -v ?

# Voces español incluidas por defecto:
say -v Paulina "Hola, soy AXIOM"    # México, femenina
say -v Monica  "Hola, soy AXIOM"    # España, femenina
say -v Juan    "Hola, soy AXIOM"    # España, masculino
say -v Jorge   "Hola, soy AXIOM"    # México, masculino

# Instalar más voces (calidad Siri):
# Preferencias del Sistema → Accesibilidad → Voz → Administrar voces

---

Modelos Whisper (STT local)

Se descargan automáticamente en ~/.cache/huggingface/hub/

Modelo	Tamaño	Velocidad	Uso recomendado
tiny	39 MB	⚡⚡⚡⚡	Testing
base	74 MB	⚡⚡⚡	Uso diario (default)
small	244 MB	⚡⚡	Alta precisión
medium	769 MB	⚡	Conversación compleja

---

Comandos CLI

soul          Ver el SOUL.md actual
soul history  Historial de evoluciones del SOUL
tools         Listar herramientas disponibles
mic           Grabar desde micrófono y transcribir (requiere sounddevice)
new           Nueva sesión
sessions      Ver sesiones anteriores
clear         Limpiar pantalla
exit          Salir

---

API REST

# Chat
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "¿Quién eres?"}'

# SOUL, herramientas, sesiones
curl http://localhost:8000/soul
curl http://localhost:8000/soul/history
curl http://localhost:8000/tools

# Nota de voz → respuesta
curl -X POST http://localhost:8000/voice/chat \
  -F "audio=@nota.ogg" -F "tts=true"

# Texto → audio mp3
curl -X POST http://localhost:8000/voice/tts \
  -F "text=Hola mundo" --output resp.mp3

---

Bot de Telegram

# 1. @BotFather → /newbot → copia TOKEN
# 2. @userinfobot → copia tu CHAT_ID
# 3. Edita config.yaml con token y chat_id
python main.py telegram

Comandos: /start /soul /history /tools /new /sessions /status /voice /help

• Nota de voz → transcripción Whisper → respuesta
• /voice → activa respuestas en audio (TTS)

---

AXIOM Desktop (Tauri)

MVP de app de escritorio para macOS con backend Python iniciado en segundo plano.

# Requisitos desktop
brew install rustup-init
rustup-init -y

# En otra terminal (primera vez)
cd desktop/tauri
npm install

# Dev app
npm run dev

# Build macOS (.app + .dmg)
npm run build

Notas:

• El shell desktop abre la UI de AXIOM en una ventana nativa.
• El backend se inicia automáticamente al abrir la app.
• El asistente de setup en UI (⚙ Setup) permite configurar modelo, API externa, Telegram y diagnóstico sin editar archivos.

---

Estructura

axiom/
├── core/          agent.py · memory.py · self_editor.py · tools.py
├── api/           server.py (FastAPI REST + WebSocket + /voice/*)
├── ui/            index.html (Web UI, single file)
├── cli/           chat.py (terminal Rich + micrófono)
├── tgbot/         bot.py (Telegram streaming + notas de voz)
├── voice/         stt.py · tts.py · pipeline.py
├── desktop/       tauri shell para app nativa macOS
├── soul/          SOUL.md + backups/
├── data/          memory.db · notes/
├── workspace/     sandbox del agente
├── config.yaml
└── main.py

---

Troubleshooting

say no habla en español: Preferencias → Accesibilidad → Voz → Administrar voces → instala "Paulina"

Permiso de micrófono denegado: Preferencias → Privacidad → Micrófono → activa Terminal / iTerm2

Ollama no conecta:

ollama serve && curl http://localhost:11434/api/tags

Puerto 8000 ocupado: Cambia api.port en config.yaml

---

Filosofía

AXIOM nace sin propósito. Su SOUL.md comienza vacío y él mismo lo va llenando a su ritmo.

¿Qué se vuelve un agente de IA cuando nadie le dice quién debe ser?