Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat: add ix savings command (#88)

Tanner Kocher7c9704401503
diff --git a/ix-cli/src/cli/commands/savings.ts b/ix-cli/src/cli/commands/savings.ts
new file mode 100644
index 00000000..7cf6a88f
--- /dev/null
+++ b/ix-cli/src/cli/commands/savings.ts
@@ -0,0 +1,157 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+
+interface CommandBreakdown {
+ count: number;
+ saved: number;
+}
+
+interface SavingsData {
+ commandCount: number;
+ tokensSaved: number;
+ naiveTokens: number;
+ actualTokens: number;
+ byCommandType: Record<string, CommandBreakdown>;
+}
+
+interface SavingsResponse {
+ session: SavingsData;
+ lifetime: SavingsData;
+}
+
+// Pricing models: input $/MTok, output $/MTok
+const PRICING: Record<string, { input: number; output: number; label: string }> = {
+ opus: { input: 15, output: 75, label: "Claude Opus ($15/MTok in, $75/MTok out)" },
+ sonnet: { input: 3, output: 15, label: "Claude Sonnet ($3/MTok in, $15/MTok out)" },
+ haiku: { input: 0.8, output: 4, label: "Claude Haiku ($0.80/MTok in, $4/MTok out)" },
+ "gpt-4o": { input: 2.5, output: 10, label: "GPT-4o ($2.50/MTok in, $10/MTok out)" },
+};
+
+const WATER_ML_PER_1K_TOKENS = 2;
+
+function estimateMoney(tokens: number, model: string): number {
+ const pricing = PRICING[model] ?? PRICING.opus;
+ // Assume ~70% input, ~30% output as a rough split
+ const inputTokens = tokens * 0.7;
+ const outputTokens = tokens * 0.3;
+ return (inputTokens * pricing.input + outputTokens * pricing.output) / 1_000_000;
+}
+
+function estimateWater(tokens: number): number {
+ return (tokens / 1000) * WATER_ML_PER_1K_TOKENS;
+}
+
+function formatTokens(n: number): string {
+ if (n >= 1_000_000) return `~${(n / 1_000_000).toFixed(1)}M`;
+ if (n >= 1_000) return `~${(n / 1_000).toFixed(1)}K`;
+ return `~${n}`;
+}
+
+function formatMoney(n: number): string {
+ return `$${n.toFixed(2)}`;
+}
+
+function formatWater(ml: number): string {
+ if (ml >= 1000) return `${(ml / 1000).toFixed(2)} liters`;
+ return `${ml.toFixed(1)} mL`;
+}
+
+function renderBlock(label: string, data: SavingsData, model: string): void {
+ const money = estimateMoney(data.tokensSaved, model);
+ const water = estimateWater(data.tokensSaved);
+ const avgPerQuery = data.commandCount > 0
+ ? Math.ceil(data.actualTokens / data.commandCount)
+ : 1;
+ const extendedQueries = avgPerQuery > 0
+ ? Math.floor(data.tokensSaved / avgPerQuery)
+ : 0;
+
+ console.log(chalk.bold(` ${label}`));
+ console.log(` ${chalk.dim("Commands run".padEnd(20))}${data.commandCount}`);
+ console.log(` ${chalk.dim("Tokens saved".padEnd(20))}${formatTokens(data.tokensSaved)}`);
+ console.log(` ${chalk.dim("Money saved".padEnd(20))}${chalk.green(formatMoney(money))}`);
+ console.log(` ${chalk.dim("Water saved".padEnd(20))}${chalk.cyan(formatWater(water))}`);
+ console.log(` ${chalk.dim("Extended usage".padEnd(20))}+${extendedQueries} queries`);
+}
+
+function renderBreakdown(label: string, byCommandType: Record<string, CommandBreakdown>): void {
+ const entries = Object.entries(byCommandType).sort((a, b) => b[1].saved - a[1].saved);
+ if (entries.length === 0) return;
+
+ console.log();
+ console.log(chalk.bold(` Breakdown (${label})`));
+ console.log(` ${"─".repeat(40)}`);
+ for (const [cmd, data] of entries) {
+ const calls = `${data.count} call${data.count === 1 ? "" : "s"}`;
+ console.log(` ${chalk.cyan(cmd.padEnd(16))}${calls.padEnd(14)}${formatTokens(data.saved)} tokens saved`);
+ }
+}
+
+export function registerSavingsCommand(program: Command): void {
+ const cmd = program
+ .command("savings")
+ .description("Show token savings from Ix usage")
+ .option("--detail", "Include per-command breakdown")
+ .option("--model <model>", "Pricing model (opus|sonnet|haiku|gpt-4o)", "opus")
+ .option("--format <fmt>", "Output format (text|json)", "text");
+
+ cmd.action(async (opts: { detail?: boolean; model: string; format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const detail = opts.detail ?? false;
+ const result: SavingsResponse = await client.savings(detail);
+
+ if (opts.format === "json") {
+ const pricing = PRICING[opts.model] ?? PRICING.opus;
+ console.log(JSON.stringify({
+ ...result,
+ computed: {
+ session: {
+ moneySaved: estimateMoney(result.session.tokensSaved, opts.model),
+ waterSavedMl: estimateWater(result.session.tokensSaved),
+ },
+ lifetime: {
+ moneySaved: estimateMoney(result.lifetime.tokensSaved, opts.model),
+ waterSavedMl: estimateWater(result.lifetime.tokensSaved),
+ },
+ pricingModel: pricing.label,
+ waterRateMlPer1kTokens: WATER_ML_PER_1K_TOKENS,
+ },
+ }, null, 2));
+ return;
+ }
+
+ const pricing = PRICING[opts.model] ?? PRICING.opus;
+
+ console.log(chalk.bold("\nIx Savings"));
+ console.log("─".repeat(42));
+ console.log();
+
+ renderBlock("This session", result.session, opts.model);
+ console.log();
+ renderBlock("All time", result.lifetime, opts.model);
+
+ if (detail) {
+ if (Object.keys(result.session.byCommandType).length > 0) {
+ renderBreakdown("this session", result.session.byCommandType);
+ }
+ if (Object.keys(result.lifetime.byCommandType).length > 0) {
+ renderBreakdown("all time", result.lifetime.byCommandType);
+ }
+ }
+
+ console.log();
+ console.log(chalk.dim(` Model: ${pricing.label}`));
+ console.log(chalk.dim(` Water rate: ${WATER_ML_PER_1K_TOKENS}mL / 1K tokens`));
+ console.log();
+ });
+
+ cmd.command("reset")
+ .description("Reset lifetime savings totals")
+ .action(async () => {
+ const client = new IxClient(getEndpoint());
+ await client.savingsReset();
+ console.log(chalk.green(" Savings data reset."));
+ });
+}
diff --git a/ix-cli/src/cli/help-text.ts b/ix-cli/src/cli/help-text.ts
index 39e6813f..23d104cc 100644
--- a/ix-cli/src/cli/help-text.ts
+++ b/ix-cli/src/cli/help-text.ts
@@ -32,6 +32,7 @@ const OSS_HELP = [
` docker <action> Manage backend`,
` view Open visualizer`,
` reset Reset map`,
+ ` savings Show token savings`,
` upgrade Update ix`,
``,
].join("\n");
diff --git a/ix-cli/src/cli/register/oss.ts b/ix-cli/src/cli/register/oss.ts
index 93141087..a68b2b25 100644
--- a/ix-cli/src/cli/register/oss.ts
+++ b/ix-cli/src/cli/register/oss.ts
@@ -33,6 +33,7 @@ import { registerSmellsCommand } from "../commands/smells.js";
import { registerSubsystemsCommand } from "../commands/subsystems.js";
import { registerUpgradeCommand } from "../commands/upgrade.js";
import { registerViewCommand } from "../commands/view.js";
+import { registerSavingsCommand } from "../commands/savings.js";
const PRO_COMMANDS: { name: string; desc: string }[] = [
{ name: "briefing", desc: "Session-resume briefing" },
@@ -94,6 +95,7 @@ export function registerOssCommands(program: Command): void {
registerTraceCommand(program);
registerUpgradeCommand(program);
registerViewCommand(program);
+ registerSavingsCommand(program);
// Hide advanced commands from default help
const advancedSet = new Set(ADVANCED_COMMANDS);
diff --git a/ix-cli/src/client/api.ts b/ix-cli/src/client/api.ts
index 81936304..3872710c 100644
--- a/ix-cli/src/client/api.ts
+++ b/ix-cli/src/client/api.ts
@@ -289,6 +289,20 @@ export class IxClient {
return resp.json() as Promise<{ ok: boolean; message: string }>;
}
+ async savings(detail?: boolean): Promise<any> {
+ const qs = detail ? "?detail=true" : "";
+ return this.get(`/v1/savings${qs}`);
+ }
+
+ async savingsReset(): Promise<any> {
+ const resp = await fetch(`${this.endpoint}/v1/savings`, { method: "DELETE" });
+ if (!resp.ok) {
+ const text = await resp.text();
+ throw new Error(`${resp.status}: ${text}`);
+ }
+ return resp.json();
+ }
+
async stats(): Promise<any> {
return this.get("/v1/stats");
}
diff --git a/memory-layer/src/main/scala/ix/memory/Main.scala b/memory-layer/src/main/scala/ix/memory/Main.scala
index 6020f93a..266a336b 100644
--- a/memory-layer/src/main/scala/ix/memory/Main.scala
+++ b/memory-layer/src/main/scala/ix/memory/Main.scala
@@ -10,6 +10,7 @@ import ix.memory.conflict.ConflictService
import ix.memory.context._
import ix.memory.db._
import ix.memory.map.MapService
+import ix.memory.savings.{NaiveCostEstimator, SavingsAccumulator, SavingsMiddleware}
import ix.memory.smell.SmellService
import ix.memory.subsystem.SubsystemScoringService
@@ -44,9 +45,12 @@ object Main extends IOApp.Simple {
mapService = new MapService(client, queryApi, writeApi)
smellService = new SmellService(client, writeApi)
subsystemService = new SubsystemScoringService(client, writeApi, mapService)
+ naiveCostEstimator = new NaiveCostEstimator(queryApi)
+ savingsAccumulator <- Resource.eval(SavingsAccumulator.create(client))
// 4. HTTP routes
- routes = Routes.all(contextService, queryApi, writeApi, conflictService, client, mapService, bulkWriteApi, smellService, subsystemService)
+ rawRoutes = Routes.all(contextService, queryApi, writeApi, conflictService, client, mapService, bulkWriteApi, smellService, subsystemService, savingsAccumulator)
+ routes = SavingsMiddleware(rawRoutes, savingsAccumulator, naiveCostEstimator)
// 5. Server
server <- EmberServerBuilder
diff --git a/memory-layer/src/main/scala/ix/memory/api/Routes.scala b/memory-layer/src/main/scala/ix/memory/api/Routes.scala
index d8dd22dd..ffe119f0 100644
--- a/memory-layer/src/main/scala/ix/memory/api/Routes.scala
+++ b/memory-layer/src/main/scala/ix/memory/api/Routes.scala
@@ -12,6 +12,7 @@ import ix.memory.conflict.ConflictService
import ix.memory.context.ContextService
import ix.memory.db.{ArangoClient, BulkWriteApi, GraphQueryApi, GraphWriteApi}
import ix.memory.map.MapService
+import ix.memory.savings.SavingsAccumulator
import ix.memory.smell.SmellService
import ix.memory.subsystem.SubsystemScoringService
@@ -26,7 +27,8 @@ object Routes {
mapService: MapService,
bulkWriteApi: BulkWriteApi,
smellService: SmellService,
- subsystemService: SubsystemScoringService
+ subsystemService: SubsystemScoringService,
+ savingsAccumulator: SavingsAccumulator
): HttpRoutes[IO] = {
val health = HttpRoutes.of[IO] {
@@ -54,12 +56,13 @@ object Routes {
val bulkPatchCommitRoutes = new BulkPatchCommitRoutes(bulkWriteApi, queryApi).routes
val smellRoutes = new SmellRoutes(smellService).routes
val subsystemRoutes = new SubsystemRoutes(subsystemService, mapService).routes
+ val savingsRoutes = new SavingsRoutes(savingsAccumulator).routes
health <+> contextRoutes <+> entityRoutes <+>
diffRoutes <+> conflictRoutes <+> decideRoutes <+> searchRoutes <+>
truthRoutes <+> patchRoutes <+> decisionListRoutes <+> expandRoutes <+>
statsRoutes <+> patchCommitRoutes <+> listRoutes <+> goalRoutes <+>
mapRoutes <+> resetRoutes <+> sourceHashRoutes <+> bulkPatchCommitRoutes <+>
- smellRoutes <+> subsystemRoutes
+ smellRoutes <+> subsystemRoutes <+> savingsRoutes
}
}
diff --git a/memory-layer/src/main/scala/ix/memory/api/SavingsRoutes.scala b/memory-layer/src/main/scala/ix/memory/api/SavingsRoutes.scala
new file mode 100644
index 00000000..ab30a645
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/api/SavingsRoutes.scala
@@ -0,0 +1,29 @@
+package ix.memory.api
+
+import cats.effect.IO
+import io.circe.syntax._
+import org.http4s.HttpRoutes
+import org.http4s.circe.CirceEntityCodec._
+import org.http4s.dsl.io._
+import org.http4s.dsl.impl.OptionalQueryParamDecoderMatcher
+
+import ix.memory.savings.SavingsAccumulator
+
+object DetailParam extends OptionalQueryParamDecoderMatcher[Boolean]("detail")
+
+class SavingsRoutes(accumulator: SavingsAccumulator) {
+
+ val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
+ case GET -> Root / "v1" / "savings" :? DetailParam(detail) =>
+ (for {
+ data <- accumulator.getSavings(detail.getOrElse(false))
+ resp <- Ok(data.asJson)
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+
+ case DELETE -> Root / "v1" / "savings" =>
+ (for {
+ _ <- accumulator.reset
+ resp <- Ok(io.circe.Json.obj("status" -> "reset".asJson))
+ } yield resp).handleErrorWith(ErrorHandler.handle(_))
+ }
+}
diff --git a/memory-layer/src/main/scala/ix/memory/db/ArangoSchema.scala b/memory-layer/src/main/scala/ix/memory/db/ArangoSchema.scala
index d4319f2c..066098f2 100644
--- a/memory-layer/src/main/scala/ix/memory/db/ArangoSchema.scala
+++ b/memory-layer/src/main/scala/ix/memory/db/ArangoSchema.scala
@@ -15,6 +15,7 @@ object ArangoSchema {
ensureCollection(db, "patches")
ensureCollection(db, "revisions")
ensureCollection(db, "idempotency_keys")
+ ensureCollection(db, "savings")
// Edge collection
ensureCollection(db, "edges", edge = true)
diff --git a/memory-layer/src/main/scala/ix/memory/savings/NaiveCostEstimator.scala b/memory-layer/src/main/scala/ix/memory/savings/NaiveCostEstimator.scala
new file mode 100644
index 00000000..8ae59f30
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/savings/NaiveCostEstimator.scala
@@ -0,0 +1,92 @@
+package ix.memory.savings
+
+import cats.effect.IO
+import io.circe.Json
+
+import ix.memory.db.{GraphQueryApi, ArangoClient}
+import ix.memory.model._
+
+/**
+ * Estimates the "naive" token cost of getting equivalent information without Ix.
+ *
+ * Uses graph-derived file sizes for entity commands (overview, impact, callers, etc.)
+ * and fixed multipliers for search/analysis commands.
+ */
+class NaiveCostEstimator(queryApi: GraphQueryApi) {
+
+ /** Fixed multipliers per command type, used when graph derivation isn't practical. */
+ private val multipliers: Map[String, Int] = Map(
+ "search" -> 6,
+ "text" -> 6,
+ "locate" -> 6,
+ "inventory" -> 8,
+ "rank" -> 8,
+ "diff" -> 5,
+ "history" -> 5,
+ "smells" -> 10,
+ "subsystems" -> 10,
+ )
+
+ private val defaultMultiplier = 4
+
+ /**
+ * Estimate naive token cost for a command.
+ *
+ * @param commandType the ix command name (e.g., "overview", "search")
+ * @param responseChars the character count of the actual response
+ * @param entityIds optional entity IDs resolved during the command
+ * @return estimated naive token count
+ */
+ def estimate(
+ commandType: String,
+ responseChars: Long,
+ entityIds: Seq[NodeId] = Seq.empty
+ ): IO[Long] = {
+ val responseTokens = math.max(1L, responseChars / 4)
+
+ commandType match {
+ case "overview" | "explain" =>
+ estimateFromGraph(entityIds, depthFactor = 3).map(_.getOrElse(responseTokens * 5))
+
+ case "impact" =>
+ estimateFromGraph(entityIds, depthFactor = 4).map(_.getOrElse(responseTokens * 8))
+
+ case "callers" | "callees" | "imported-by" | "imports" =>
+ estimateFromGraph(entityIds, depthFactor = 2).map(_.getOrElse(responseTokens * 4))
+
+ case "contains" =>
+ estimateFromGraph(entityIds, depthFactor = 1).map(_.getOrElse(responseTokens * 3))
+
+ case "depends" =>
+ estimateFromGraph(entityIds, depthFactor = 3).map(_.getOrElse(responseTokens * 6))
+
+ case cmd =>
+ val mult = multipliers.getOrElse(cmd, defaultMultiplier)
+ IO.pure(responseTokens * mult)
+ }
+ }
+
+ /**
+ * Estimate by summing actual file sizes of involved entities from the graph.
+ * Returns None if no entities are available.
+ */
+ private def estimateFromGraph(entityIds: Seq[NodeId], depthFactor: Int): IO[Option[Long]] = {
+ if (entityIds.isEmpty) return IO.pure(None)
+
+ entityIds.toList.foldLeft(IO.pure(0L)) { (accIO, nodeId) =>
+ for {
+ acc <- accIO
+ nodeOpt <- queryApi.getNode(nodeId)
+ size: Long = nodeOpt.map { node =>
+ val attrsC = node.attrs.hcursor
+ attrsC.get[Long]("line_end").toOption.map(_ * 80L) // estimate chars from line count
+ .orElse(attrsC.get[String]("source_uri").toOption.map(_ => 2000L)) // fallback: 2KB per file
+ .getOrElse(1000L) // default estimate
+ }.getOrElse(1000L)
+ } yield acc + size
+ }.map { totalChars =>
+ val tokens = totalChars / 4 * depthFactor
+ Some(math.max(tokens, 100L))
+ }
+ }
+}
diff --git a/memory-layer/src/main/scala/ix/memory/savings/SavingsAccumulator.scala b/memory-layer/src/main/scala/ix/memory/savings/SavingsAccumulator.scala
new file mode 100644
index 00000000..ff29cf36
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/savings/SavingsAccumulator.scala
@@ -0,0 +1,151 @@
+package ix.memory.savings
+
+import cats.effect.{IO, Ref}
+import io.circe.{Encoder, Json}
+import io.circe.syntax._
+
+import ix.memory.db.ArangoClient
+
+/** Tracks token savings per session (in-memory) and lifetime (ArangoDB). */
+class SavingsAccumulator(client: ArangoClient, session: Ref[IO, SavingsData]) {
+
+ /** Record savings for a single command invocation. Fire-and-forget safe. */
+ def record(commandType: String, actualTokens: Long, naiveEstimate: Long): IO[Unit] = {
+ val saved = math.max(0L, naiveEstimate - actualTokens)
+ val entry = CommandSavings(count = 1, saved = saved)
+ for {
+ _ <- session.update(_.add(commandType, actualTokens, naiveEstimate, saved))
+ _ <- persistLifetime(commandType, actualTokens, naiveEstimate, saved)
+ } yield ()
+ }
+
+ /** Get current savings data. */
+ def getSavings(detail: Boolean): IO[SavingsResponse] =
+ for {
+ sess <- session.get
+ lifetime <- loadLifetime
+ } yield SavingsResponse(
+ session = if (detail) sess else sess.withoutBreakdown,
+ lifetime = if (detail) lifetime else lifetime.withoutBreakdown
+ )
+
+ /** Reset lifetime totals. */
+ def reset: IO[Unit] =
+ for {
+ _ <- session.set(SavingsData.empty)
+ _ <- client.execute(
+ """UPSERT { _key: "lifetime" }
+ |INSERT { _key: "lifetime", totalSaved: 0, totalNaive: 0, totalActual: 0,
+ | commandCount: 0, byCommandType: {}, lastUpdated: DATE_ISO8601(DATE_NOW()) }
+ |UPDATE { totalSaved: 0, totalNaive: 0, totalActual: 0,
+ | commandCount: 0, byCommandType: {}, lastUpdated: DATE_ISO8601(DATE_NOW()) }
+ |IN savings""".stripMargin
+ )
+ } yield ()
+
+ private def persistLifetime(
+ commandType: String, actual: Long, naive: Long, saved: Long
+ ): IO[Unit] =
+ client.execute(
+ """UPSERT { _key: "lifetime" }
+ |INSERT { _key: "lifetime", totalSaved: @saved, totalNaive: @naive, totalActual: @actual,
+ | commandCount: 1, byCommandType: { [@cmd]: { count: 1, saved: @saved } },
+ | lastUpdated: DATE_ISO8601(DATE_NOW()) }
+ |UPDATE {
+ | totalSaved: OLD.totalSaved + @saved,
+ | totalNaive: OLD.totalNaive + @naive,
+ | totalActual: OLD.totalActual + @actual,
+ | commandCount: OLD.commandCount + 1,
+ | byCommandType: MERGE(OLD.byCommandType, {
+ | [@cmd]: {
+ | count: (HAS(OLD.byCommandType, @cmd) ? OLD.byCommandType[@cmd].count : 0) + 1,
+ | saved: (HAS(OLD.byCommandType, @cmd) ? OLD.byCommandType[@cmd].saved : 0) + @saved
+ | }
+ | }),
+ | lastUpdated: DATE_ISO8601(DATE_NOW())
+ |} IN savings""".stripMargin,
+ Map(
+ "saved" -> Long.box(saved).asInstanceOf[AnyRef],
+ "naive" -> Long.box(naive).asInstanceOf[AnyRef],
+ "actual" -> Long.box(actual).asInstanceOf[AnyRef],
+ "cmd" -> commandType.asInstanceOf[AnyRef]
+ )
+ )
+
+ private def loadLifetime: IO[SavingsData] =
+ client.queryOne(
+ """FOR doc IN savings FILTER doc._key == "lifetime" RETURN doc""",
+ Map.empty[String, AnyRef]
+ ).map {
+ case Some(json) =>
+ val c = json.hcursor
+ val byCmd = c.downField("byCommandType").focus
+ .flatMap(_.asObject)
+ .map { obj =>
+ obj.toMap.map { case (k, v) =>
+ val vc = v.hcursor
+ k -> CommandSavings(
+ count = vc.get[Long]("count").getOrElse(0L),
+ saved = vc.get[Long]("saved").getOrElse(0L)
+ )
+ }
+ }.getOrElse(Map.empty)
+ SavingsData(
+ totalSaved = c.get[Long]("totalSaved").getOrElse(0L),
+ totalNaive = c.get[Long]("totalNaive").getOrElse(0L),
+ totalActual = c.get[Long]("totalActual").getOrElse(0L),
+ commandCount = c.get[Long]("commandCount").getOrElse(0L),
+ byCommandType = byCmd
+ )
+ case None => SavingsData.empty
+ }
+}
+
+object SavingsAccumulator {
+ def create(client: ArangoClient): IO[SavingsAccumulator] =
+ Ref.of[IO, SavingsData](SavingsData.empty).map(new SavingsAccumulator(client, _))
+}
+
+case class CommandSavings(count: Long, saved: Long)
+
+object CommandSavings {
+ implicit val encoder: Encoder[CommandSavings] = Encoder.forProduct2("count", "saved")(cs =>
+ (cs.count, cs.saved))
+}
+
+case class SavingsData(
+ totalSaved: Long,
+ totalNaive: Long,
+ totalActual: Long,
+ commandCount: Long,
+ byCommandType: Map[String, CommandSavings]
+) {
+ def add(cmd: String, actual: Long, naive: Long, saved: Long): SavingsData = {
+ val existing = byCommandType.getOrElse(cmd, CommandSavings(0, 0))
+ copy(
+ totalSaved = totalSaved + saved,
+ totalNaive = totalNaive + naive,
+ totalActual = totalActual + actual,
+ commandCount = commandCount + 1,
+ byCommandType = byCommandType.updated(cmd,
+ CommandSavings(existing.count + 1, existing.saved + saved))
+ )
+ }
+
+ def withoutBreakdown: SavingsData = copy(byCommandType = Map.empty)
+}
+
+object SavingsData {
+ val empty: SavingsData = SavingsData(0, 0, 0, 0, Map.empty)
+
+ implicit val encoder: Encoder[SavingsData] = Encoder.forProduct5(
+ "commandCount", "tokensSaved", "naiveTokens", "actualTokens", "byCommandType"
+ )(d => (d.commandCount, d.totalSaved, d.totalNaive, d.totalActual, d.byCommandType))
+}
+
+case class SavingsResponse(session: SavingsData, lifetime: SavingsData)
+
+object SavingsResponse {
+ implicit val encoder: Encoder[SavingsResponse] = Encoder.forProduct2("session", "lifetime")(r =>
+ (r.session, r.lifetime))
+}
diff --git a/memory-layer/src/main/scala/ix/memory/savings/SavingsMiddleware.scala b/memory-layer/src/main/scala/ix/memory/savings/SavingsMiddleware.scala
new file mode 100644
index 00000000..32922d8d
--- /dev/null
+++ b/memory-layer/src/main/scala/ix/memory/savings/SavingsMiddleware.scala
@@ -0,0 +1,73 @@
+package ix.memory.savings
+
+import cats.data.Kleisli
+import cats.effect.IO
+import org.http4s.{HttpRoutes, Request, Response}
+
+// Middleware that intercepts responses from /v1/* routes and records
+// token savings. Runs as a fire-and-forget side effect.
+object SavingsMiddleware {
+
+ // Routes that should not be tracked (meta/health endpoints).
+ private val excludedPaths = Set("health", "savings", "stats")
+
+ def apply(
+ routes: HttpRoutes[IO],
+ accumulator: SavingsAccumulator,
+ estimator: NaiveCostEstimator
+ ): HttpRoutes[IO] = Kleisli { (req: Request[IO]) =>
+ routes(req).semiflatMap { response =>
+ extractCommandType(req) match {
+ case Some(cmd) if !excludedPaths.contains(cmd) =>
+ // Read the response body to measure size, then reconstruct it
+ response.body.compile.toVector.flatMap { bodyBytes =>
+ val responseChars = bodyBytes.length.toLong
+ val recordIO = for {
+ naiveEstimate <- estimator.estimate(cmd, responseChars)
+ actualTokens = math.max(1L, responseChars / 4)
+ _ <- accumulator.record(cmd, actualTokens, naiveEstimate)
+ } yield ()
+
+ // Fire-and-forget: don't let savings tracking failure affect the response
+ recordIO.attempt.void.as(
+ response.withBodyStream(fs2.Stream.emits(bodyBytes))
+ )
+ }
+
+ case _ => IO.pure(response)
+ }
+ }
+ }
+
+ // Extract the command type from the request path.
+ private def extractCommandType(req: Request[IO]): Option[String] = {
+ val segments = req.pathInfo.renderString.stripPrefix("/").split("/").toList
+ segments match {
+ case "v1" :: cmd :: _ => Some(mapPathToCommand(cmd))
+ case _ => None
+ }
+ }
+
+ // Map URL path segments to logical command names.
+ private def mapPathToCommand(segment: String): String = segment match {
+ case "context" => "query"
+ case "search" => "search"
+ case "entity" => "entity"
+ case "expand" => "callers"
+ case "expand-by-name"=> "callers"
+ case "diff" => "diff"
+ case "conflicts" => "conflicts"
+ case "decide" => "decide"
+ case "truth" => "truth"
+ case "patches" => "history"
+ case "map" => "map"
+ case "list" => "inventory"
+ case "decisions" => "decisions"
+ case "smells" => "smells"
+ case "subsystems" => "subsystems"
+ case "provenance" => "history"
+ case "resolve-prefix"=> "locate"
+ case "ingest" => "map"
+ case other => other
+ }
+}
diff --git a/memory-layer/src/test/scala/ix/memory/api/RoutesSpec.scala b/memory-layer/src/test/scala/ix/memory/api/RoutesSpec.scala
index b6f67e6a..080a4074 100644
--- a/memory-layer/src/test/scala/ix/memory/api/RoutesSpec.scala
+++ b/memory-layer/src/test/scala/ix/memory/api/RoutesSpec.scala
@@ -19,6 +19,7 @@ import ix.memory.context._
import ix.memory.db._
import ix.memory.map.MapService
import ix.memory.model._
+import ix.memory.savings.SavingsAccumulator
import ix.memory.smell.SmellService
import ix.memory.subsystem.SubsystemScoringService
@@ -68,6 +69,7 @@ class RoutesSpec extends AsyncFlatSpec with AsyncIOSpec with Matchers with TestD
val mapService = new MapService(client, queryApi, writeApi)
val smellService = new SmellService(client, writeApi)
val subsystemService = new SubsystemScoringService(client, writeApi, mapService)
+ val savingsAccumulator = SavingsAccumulator.create(client).unsafeRunSync()(ioRuntime)
Routes.all(
contextService,
@@ -78,7 +80,8 @@ class RoutesSpec extends AsyncFlatSpec with AsyncIOSpec with Matchers with TestD
mapService,
bulkWriteApi,
smellService,
- subsystemService
+ subsystemService,
+ savingsAccumulator
).orNotFound
}