coulomb/fin-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Resource viability hub for budgets, commitments, burn rate, runway projection, and token spend tracking.
21 commits 1 branch 0 tags 769 KiB
Find a file
tegwick 8338c501ed Add engagement margin reporting
2026-08-10 20:43:05 +02:00
.claude/rules Implement FIN-WP-0001-T06 HTTP runway read surface 2026-07-08 22:46:24 +02:00
.forgejo/workflows Add Forgejo CI smoke workflow (enablement template) 2026-07-08 12:43:08 +02:00
docs Implement FIN-WP-0001 ledger, evaluate, and evidence lane (T03–T05) 2026-07-08 22:44:07 +02:00
src/fin_hub Add engagement margin reporting 2026-08-10 20:43:05 +02:00
tests Add engagement margin reporting 2026-08-10 20:43:05 +02:00
workplans Add engagement margin reporting 2026-08-10 20:43:05 +02:00
.custodian-brief.md Add engagement margin reporting 2026-08-10 20:43:05 +02:00
.gitignore Implement FIN-WP-0001 ledger, evaluate, and evidence lane (T03–T05) 2026-07-08 22:44:07 +02:00
.repo-classification.yaml Complete fin-hub repo integration (FIN-WP-0000) 2026-07-08 22:39:22 +02:00
AGENTS.md docs: workplan-first agent guidance prose (CUST-WP-0055 T04 batch 4) 2026-07-08 17:22:15 +02:00
CLAUDE.md Complete fin-hub repo integration (FIN-WP-0000) 2026-07-08 22:39:22 +02:00
INTENT.md docs: add trailing newline to INTENT.md 2026-07-08 22:42:11 +02:00
LICENSE Adopt Target Revenue Source License V1C1 (org-wide preliminary rollout) 2026-07-30 00:11:23 +02:00
pyproject.toml Implement fin-hub T24-T26: ingest, runway, coupling, RaaS packaging 2026-07-08 00:59:39 +02:00
README.md Add engagement margin reporting 2026-08-10 20:43:05 +02:00
SCOPE.md Add client billing and cost evidence workplans 2026-08-10 20:12:05 +02:00
uv.lock Bootstrap fin-hub scaffold from hub-core (CUST-WP-0025-T22/T23) 2026-07-08 00:50:24 +02:00
WORK-RECORDS.md Add engagement margin reporting 2026-08-10 20:43:05 +02:00

README.md

Fin Hub

Resource viability hub for the FOS federation — budgets, commitments, burn rate, runway projection, and token spend tracking.

Fin-hub extends hub-core with financial models and read surfaces. Generic hub primitives (domains, repos, messages, progress events) come from hub-core; fin-specific models (budget, commitment, burn rate, runway, token spend) live here.

Status

MVP complete (CUST-WP-0025 T22–T26): models, CSV ingest, runway CLI, FOS coupling, RaaS packaging draft. Operational hardening tracked in workplans/FIN-WP-0001-runway-operations-lane.md.

Quick Start

cd /home/worsch/fin-hub
uv sync
uv run pytest
uv run finhub runway --balance 12000 --monthly-burn 2100,2200,2000
uv run finhub ledger import cloud tests/fixtures/cloud-costs.csv
uv run finhub ledger set-price --client acme --application portal --instance prod-01 --period 2026-07 --amount 100 --source agreement-2026-01
uv run finhub ledger margins
uv run finhub evaluate
uv run finhub evidence --seed-fixtures
uv run finhub serve
uv run finhub import-cloud tests/fixtures/cloud-costs.csv
uv run finhub ops-costs tests/fixtures/hosteurope.csv

Cross-hub coupling (--emit) posts non-secret progress events to dev-hub when STATE_HUB_API is reachable.

Client cost attribution

HostEurope CSV rows may include client_id, application_id, and app_instance_id. All three must be present together. Fin-hub validates them as external identifiers and derives the stable key client:<client_id>|app:<application_id>|instance:<app_instance_id>; callers must not invent a second key format. Rows without all three columns remain explicitly unattributed for backward compatibility.

The SQLite ledger adds the attribution columns automatically when an existing ledger is opened. The ops-costs report retains its per-service view and adds an attributions view separated by currency. Client and application identity remain authoritative outside fin-hub.

Engagement prices are reporting entitlements, not invoices or received payments. A price is identified by client/application/instance, reporting month, and currency. Corrections are append-only: pass the current record ID to ledger set-price --revision-of; margin reports use the newest revision and preserve the earlier price for auditability.

Related Workplans

  • the-custodian/workplans/CUST-WP-0025-fos-hub-bootstrap.md — umbrella
  • canon/constitution/bootstrap-protocol_v0.1.md — funding and roles
  • canon/projects/railiance/business-model-canvas_v0.1.md — monetization path