BytIA KODE

BytIA KODE (B-KODE) es un agente de IA para terminal: identidad configurable en YAML, arquitectura multi-provider con failover automático, skills extensibles y sesiones persistentes. Corre como TUI (Textual) y como bot de Telegram — ambas interfaces comparten la misma base de datos de sesiones en SQLite. Pensado para trabajar sobre tu código: tools nativas con perímetro de seguridad (allowlist de binarios, sandbox de paths) y cero dependencias de servicios en la nube para el núcleo.

Instalación

El paquete vive en PyPI: pip install bytia-kode (o uv tool install bytia-kode) es el camino canónico. El git clone queda solo para desarrollo (ver Desarrollo).

Instalación rápida (recomendada)

curl -fsSL https://raw.githubusercontent.com/asturwebs/BytIA-KODE/main/install.sh | bash

Esto instala todo automáticamente: bootstrap de uv si falta, instalación de bytia-kode desde PyPI como tool aislada (bytia-kode en ~/.local/bin), y genera ~/.bytia-kode/.env con valores por defecto. Solo necesitas editar ese .env con tu provider y API key.

Instalación manual (desde PyPI)

# con uv (recomendado: entorno aislado, Python gestionado, binario en ~/.local/bin)
uv tool install bytia-kode

# o con pip, dentro de un venv
pip install bytia-kode

Luego crea tu configuración global (el instalador rápido lo hace por ti):

mkdir -p ~/.bytia-kode
cat > ~/.bytia-kode/.env << 'EOF'
PROVIDER_BASE_URL=http://localhost:8080/v1
PROVIDER_API_KEY=not-needed
PROVIDER_MODEL=auto
EOF
# editar con tu provider y API key — todas las variables: .env.example del repo

Un .env en el directorio de trabajo (proyecto) tiene precedencia sobre el global ~/.bytia-kode/.env. Las skills vendor se siembran solas en ~/.bytia-kode/skills/vendor/ en el primer arranque — y se actualizan solas cuando la versión instalada cambia.

Quickstart

bytia-kode --version    # versión instalada (+ build id si existe) y sale
bytia-kode              # TUI (por defecto)
bytia-kode --bot        # bot de Telegram

La TUI pide lo mínimo: el .env con tu provider (ver Instalación) y, para el bot, TELEGRAM_BOT_TOKEN. Dentro de la TUI, Ctrl+P abre el menú de comandos y /help resume todo.

Características

• Multi-provider con failover automático — cadena local-first (router → Ollama → nube) con circuit breaker (CLOSED → OPEN → HALF_OPEN): si el primario cae, el agente cambia solo y se recupera a los 60 s. Pin manual por teclas F1–F8.
• Sesiones persistentes — todo se guarda en SQLite WAL (~/.bytia-kode/sessions.db), compartido entre TUI y Telegram: empieza un chat en una interfaz y résumelo en la otra. Auto-save O(1) por mensaje.
• Sistema de skills por capas — procedimientos Markdown+YAML en ~/.bytia-kode/skills/ con prioridad bytia > user > vendor; las vendor se siembran y actualizan automáticamente con el paquete.
• Tools nativas con perímetro de seguridad — 12 tools (bash, files, grep/glob/tree, web_fetch, sesiones) tras un modelo defense-in-depth: allowlist de binarios, jail de workspace configurable (confined/permissive/open, ver Política de workspace), SSRF cerrada, redacción de secretos en logs.
• Identidad configurable en YAML — kernel.default.yaml (identidad y valores) + runtime.default.yaml (adaptación al entorno), empaquetados como recursos; overrides de usuario en ~/.bytia-kode/prompts/.
• Bot de Telegram — mismo cerebro y mismas sesiones, aislamiento por usuario, fail-secure sin allowlist.
• Motor I/O asíncrono — benchmark 4.90x frente a ejecución secuencial (medición histórica 2026-04, docs/devlog/2026-04-02.md; no hay benchmark reproducible en el repo).

Modos de ejecución

En desarrollo: uv run bytia-kode y uv run python -m bytia_kode --bot.

Configuración principal

Además de las variables de entorno, ~/.bytia-kode/config.yaml configura la política de workspace (ver abajo).

Política de workspace

El agente corre tras un jail de intención configurable: ~/.bytia-kode/config.yaml decide qué puede tocar.

workspace:
  mode: confined          # confined | permissive | open (default: permissive)
  trusted_paths:          # válvula de precisión: rutas permitidas además del workspace
    - ~/Projects
    - ~/bytia

• Es una política de intención, no un sandbox de kernel: se rechaza lo que el agente pide por nombre (rutas absolutas, ~/…, rutas relativas con /; los saltos por symlink se canonicalizan con Path.resolve()). Un binario permitido que recorra el árbol por su cuenta (p. ej. git leyendo ~/.gitconfig) o un fichero dentro del workspace enlazado hacia fuera quedan fuera de lo que esto puede garantizar. Sin namespaces/chroot por diseño.
• Conmutación en caliente: /workspace en la TUI (o Ctrl+P → Workspace mode) muestra el modo activo —también visible en la barra de estado (ws:confined en verde, ws:permissive en ámbar, ws:open en rojo)— y conmuta con confirmación. El cambio aplica a la sesión en curso y no se persiste: para hacerlo permanente, edítalo tú en config.yaml.
• Errores accionables: cada bloqueo nombra el modo activo, los límites del jail y las dos salidas (ampliar trusted_paths o conmutar el modo) — el agente no tiene que adivinar.
• config.yaml es del operador: el agente no puede escribirlo (denylist T4, igual que .env o mcp_servers.json) — una sesión inyectada no puede silenciosamente pasar el jail a open para el siguiente arranque. Ese denylist sigue activo en los tres modos: open libera el workspace, nunca la superficie de configuración propia del agente.
• Sin config.yaml (o malformado) el arranque es permissive — el comportamiento histórico, ahora explícito y documentado.

Sesiones persistentes

Las sesiones se almacenan en ~/.bytia-kode/sessions.db (SQLite WAL mode). Tanto la TUI como el bot de Telegram comparten la misma base de datos.

El modelo también puede acceder a sesiones pasadas durante la conversación: session_list, session_load, session_search.

Skills System

Las skills son procedimientos reutilizables en formato Markdown+YAML que el agente carga en su system prompt según relevancia (las relevantes al query se inyectan automáticamente).

~/.bytia-kode/skills/
├── bytia/      # Ecosistema BytIA (opcional, si ~/bytia existe)
├── user/       # Skills creadas por el usuario (writable)
└── vendor/     # Skills incluidas con KODE (read-only, auto-update)

Capas superiores sobrescriben las inferiores con el mismo nombre. Skills vendor incluidas: bytia-constitution (identidad y valores), bytia-memory (memoria entre sesiones), skills-manager (gestión del sistema), graphify (knowledge graphs de código).

Tools

Seguridad

Modelo de seguridad con defense-in-depth:

Guardarraíl JEVAL (pre-ejecución de tools)

src/bytia_kode/guardrail.py clasifica cada llamada a tool antes de ejecutarla (TypeSafe System One) y puede bloquear las arriesgadas.

Por defecto off; requiere TYPESAFE_API_KEY (sin clave, el gate se desactiva aunque JEVAL_MODE=enforce); fail-open ante error del clasificador. Otras variables: JEVAL_THRESHOLD (0..1, default 0.7), JEVAL_TIMEOUT (default 2.0 s). Log de decisiones: ~/.local/state/jev-router/kode-guardrail.jsonl.

Limitaciones conocidas

• safe_mode sigue siendo principalmente visual y no implementa aislamiento backend completo.
• El cliente MCP es WIP declarado (stubs no-op sin el extra [mcp]; McpTool.execute() pendiente) — no anunciarlo como capacidad terminada.
• El estimador de tokens es una heurística (chars/3–3.5 según densidad ASCII), no un tokenizer real.
• PromptTextArea no soporta Shift+Enter para newline (limitación de Textual).

Arquitectura

__main__.py                     ← entry point: --version / --bot / TUI
  ├─ tui.py
  └─ telegram/bot.py

agent.py
  ├─ prompts/kernel.default.yaml + runtime.default.yaml (identidad; overrides de usuario en ~/.bytia-kode/prompts/)
  ├─ session.py                 ← SQLite WAL persistence
  ├─ providers/manager.py
  ├─ providers/circuit.py       ← Circuit breaker (CLOSED/OPEN/HALF_OPEN)
  ├─ providers/client.py
  ├─ tools/registry.py
  ├─ tools/session.py           ← session_list, session_load, session_search
  └─ skills/loader.py

audio.py                        ← TTS: bytia-tts + piper (local)

Stack técnico

Identidad: BytIA OS Kernel + Runtime

El agente carga su identidad desde dos YAML: los defaults empaquetados como recursos del paquete (kernel.default.yaml + runtime.default.yaml en src/bytia_kode/prompts/) y, encima, tus overrides bytia.kernel.yaml / bytia.runtime.kode.yaml en ~/.bytia-kode/prompts/ — deep-merge sobre los defaults, sin reconstruir nada. Para cambiar los defaults del paquete: edita los YAML en src/bytia_kode/prompts/ y reconstruye el wheel (uv build).

Bot de Telegram

El bot comparte la misma base de datos de sesiones que la TUI (~/.bytia-kode/sessions.db):

• Continuar conversaciones entre interfaces — empieza un chat en Telegram y résumelo en la TUI (y viceversa).
• Aislamiento por usuario — cada chat_id tiene su propia sesión e historial privado. No hay filtrado de contenido.
• Acceso del modelo — el agente puede usar session_list(source="telegram") para acceder a sesiones de Telegram desde la TUI.

Configuración

Sin TELEGRAM_ALLOWED_USERS configurado, el bot deniega todos los mensajes (fail-secure).

Al arrancar, el bot imprime por stdout un banner con el token enmascarado y el número de usuarios permitidos, y queda a la escucha — se detiene limpio con un Ctrl+C:

Bot de Telegram activo · token 123456789:AAF…x7Q · usuarios permitidos: 2 · esperando mensajes (Ctrl+C para parar)

Comandos del bot

TUI

Comandos

Atajos

Temas

Pulsa F2 para cambiar entre los 19 temas disponibles (12 oscuros + 7 claros, por defecto gruvbox). El tema se guarda en ~/.bytia-kode/theme.json.

Desarrollo

git clone https://github.com/asturwebs/BytIA-KODE.git
cd BytIA-KODE
uv sync
uv run bytia-kode

Validación

uv run python scripts/validate_metadata.py
uv run python scripts/check_readme_claims.py
uv run pytest -q
uv build
uv run python -m twine check dist/*

Publicación

Las versiones se publican automáticamente por Trusted Publishers (OIDC): push de un tag v* → .github/workflows/release.yml corre los gates, construye con uv build, publica vía pypa/gh-action-pypi-publish en el environment pypi (aprobación del Socio), y crea la GitHub Release con las notas del CHANGELOG. Cero secretos en el repo. El proceso completo, paso a paso: RELEASING.md.

Hook local versionado

git config core.hooksPath .githooks

Contribuir

1. Fork del repositorio
2. Rama para tu feature (git checkout -b feature/mi-mejora)
3. Commit con cambios (git commit -m 'feat: descripción')
4. Push a la rama (git push origin feature/mi-mejora)
5. Abre un Pull Request

Consulta CONTRIBUTING.md para los criterios de validación.

Documentación

• Manual de la TUI
• Arquitectura técnica
• Guía de desarrollo
• Proceso de release
• Guía de contribución
• Código de conducta

Historial completo de versiones: CHANGELOG.md.

Autores

• Pedro Luis Cuevas Villarrubia (AsturWebs) <pedro@asturwebs.es>
• BytIA v12.3.0 — coautoría operativa — BytIA OS RFC-001

Licencia

Licencia MIT. Consulta LICENSE.