Zbill

Zbill analiza código en tu máquina y propone dónde medir ROI con 9 métricas Zpulse v2: impacto (time_saved, errors_reduced, value_generated) y costo (cost_llm, cost_compute, cost_api, cost_storage, cost_human, cost_other).

Ver el código en GitHub

Instalación

git clone https://github.com/angievic/zbill.git
cd zbill
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
zbills --version

Comandos

Subcomandos

Comando	Argumentos	Qué hace
`zbills init`	`[path]` → default `.`	Crea `.zbills.env.example` (plantilla de variables para ingest y LLM).
`zbills analyze`	`[path]` → default `.`	Crea una carpeta única `…-zbill-runtime` con `zbills_report.json`, `zbills_suggestions.md` y `zbills_runtime_report.html`.
`zbills suggest`	`[path]` → default `.`	Usa el JSON en esa ruta o el informe más reciente en `*/-zbill-runtime/`. Imprime categoría, métrica y `fields`.
`zbills --version`	—	Muestra la versión instalada.

Opciones de `zbills analyze`

Opción	Default	Descripción
`-o`, `--output-dir`	raíz analizada	Directorio padre donde se crea la subcarpeta `*-zbill-runtime`.
`--max`	sin límite	Tope de hallazgos (ordenados por score).
`--llm`	off	Enriquece los mejores hallazgos con un LLM.
`--provider`	variable de entorno	`ollama`, `openai`, `anthropic`, `gemini`.
`--model`	env / default del proveedor	Nombre del modelo (p. ej. `mistral`, `gpt-4o-mini`).
`--llm-top`	`15`	Cuántos hallazgos enviar al modelo.

Opciones de `zbills suggest`

Opción	Default	Descripción
`--limit`	`20`	Máximo de entradas a imprimir.

Métricas (v2)

Impacto (numerador): time_saved, errors_reduced, value_generated — category: impact.
Costo (denominador): cost_llm, cost_compute, cost_api, cost_storage, cost_human, cost_other — category: cost.

Los informes (zbills_report.json, zbills_suggestions.md, zbills_runtime_report.html) incluyen suggestion (snippet zbills.track), fields.required / fields.optional y, en HTML, tablas separadas de impacto vs costo más una vista previa de la fórmula ROI.

Ingest: POST {URL_PREFIX}/api/v1/events con Authorization: Bearer {API_KEY}. Resumen: GET {URL_PREFIX}/api/v1/summary?days=30 devuelve total_impact_usd, total_cost_usd, total_roi_percent.

cost_llm: validar que value ≈ cost_input + cost_output (tolerancia 0.01).

Flujo recomendado

zbills init en la raíz del repo cliente.
zbills analyze .
Revisar zbills_suggestions.md o zbills_report.json.
Opcional: zbills analyze . --llm (Ollama local por defecto).
Abre zbills_runtime_report.html de la última carpeta *-zbill-runtime.
zbills suggest . para ver ejemplos track() en consola.

Lenguajes soportados

Python (AST), Go, JavaScript, TypeScript, Java y Ruby (heurísticas). Se saltan node_modules, .git, entornos virtuales y artefactos de build habituales.

LLM y Ollama

Default: proveedor ollama, modelo mistral.
Gemini (default de modelo): gemini-3.1-flash-lite-preview si no defines ZBILLS_LLM_MODEL.
Cloud: define la API key correspondiente y ZBILLS_LLM_PROVIDER.
macOS/Linux: si falta el modelo en Ollama, zbills puede ejecutar ollama pull.
Windows: se muestran instrucciones y enlace de descarga; el pull es manual.

Tabla rápida de variables:

Variable	Rol
`ZBILLS_LLM_PROVIDER`	Proveedor activo.
`ZBILLS_LLM_MODEL`	Modelo.
`OPENAI_API_KEY`	OpenAI.
`ANTHROPIC_API_KEY`	Anthropic.
`GOOGLE_API_KEY` / `GEMINI_API_KEY`	Gemini.
`OLLAMA_HOST`	URL del daemon Ollama.

Más detalle

El README del repositorio incluye la misma referencia ampliada (tablas, ejemplos y notas de Pages).

Si en GitHub Pages no ves los colores crema / marrón: en _config.yml, baseurl debe coincidir con el nombre del repositorio (p. ej. "/zbill"). En GitHub Actions el CSS también se resuelve con site.github.url. Tras corregir, espera el deploy y prueba recarga forzada (Ctrl+F5 / vaciar caché).