@redstone-md/mapr 0.0.3-alpha → 0.0.4-alpha

package/README.md

@@ -16,6 +16,7 @@ This repository is public for source visibility and collaboration. The license r
 - Same-origin crawler with bounded page count and crawl depth
 - JS bundle, worker, service worker, WASM, and source-map discovery
 - Iframe-aware crawling for same-origin embedded pages
+- Streaming AI generation with live throughput updates in the TUI
 - Local RAG mode for multi-megabyte bundles
 - Partial-report persistence when analysis fails mid-run
 - Headless automation mode for CI or batch workflows
@@ -41,7 +42,7 @@ Mapr does not analyze images, fonts, audio, video, PDFs, archives, or other pres
 - Built-in OpenAI-compatible presets for BlackBox AI, Nvidia NIM, and OnlySQ
 - Automatic model context-size detection from provider model metadata when available
 - Headless CLI mode for automation
-- Live crawler and swarm progress with agent-level tracking and progress bars
+- Live crawler and swarm progress with agent-level tracking, progress bars, and streaming TPS estimates
 
 ## Install
 
@@ -66,7 +67,7 @@ npx @redstone-md/mapr --help
 4. Crawl the target website, same-origin iframe pages, and discovered code artifacts with bounded page count and crawl depth
 5. Format analyzable content where possible
 6. Optionally build a local lexical RAG index for oversized artifacts
-7. Run a communicating swarm of analysis agents over chunked artifact content with structured-output fallback for providers that only support plain text
+7. Run a communicating swarm of analysis agents over chunked artifact content through streaming JSON generation so long-running requests keep producing output
 8. Generate a Markdown report in the current working directory
 
 ## Provider Presets
@@ -123,7 +124,7 @@ Mapr uses a communicating agent swarm per chunk:
 - `security`: identifies risks, persistence, caching, and operator tips
 - `synthesizer`: merges the upstream notes into the final chunk analysis
 
-Progress is shown directly in the TUI for crawler fetches, depth skips, discovered nested artifacts, and swarm agent/chunk execution.
+Progress is shown directly in the TUI for crawler fetches, depth skips, discovered nested artifacts, swarm agent/chunk execution, and live token-per-second estimates during provider streaming.
 
 ## Large Bundle Handling
 

package/lib/ai-analyzer.ts

@@ -13,7 +13,7 @@ import {
   type ChunkAnalysis,
   PartialAnalysisError,
 } from "./analysis-schema";
-import { generateObjectWithTextFallback } from "./ai-json";
+import { generateObjectFromStream, type StreamedObjectTelemetry } from "./ai-json";
 import { artifactTypeSchema } from "./artifacts";
 import type { FormattedArtifact } from "./formatter";
 import { LocalArtifactRag } from "./local-rag";
@@ -38,7 +38,7 @@ const analyzeInputSchema = z.object({
   ),
 });
 export type AnalysisProgressStage = "artifact" | "chunk" | "agent";
-export type AnalysisProgressState = "started" | "completed";
+export type AnalysisProgressState = "started" | "streaming" | "completed";
 
 export interface AnalysisProgressEvent {
   stage: AnalysisProgressStage;
@@ -50,6 +50,9 @@ export interface AnalysisProgressEvent {
   chunkIndex?: number;
   chunkCount?: number;
   agent?: SwarmAgentName;
+  estimatedOutputTokens?: number;
+  outputTokens?: number;
+  tokensPerSecond?: number;
 }
 
 interface AnalyzerOptions {
@@ -153,6 +156,13 @@ function normalizeAiError(error: unknown): Error {
   return error;
 }
 
+function formatAgentTelemetrySuffix(telemetry: StreamedObjectTelemetry): string {
+  const tokenCount = telemetry.outputTokens ?? telemetry.estimatedOutputTokens;
+  const tokenLabel = telemetry.outputTokens !== undefined ? `${tokenCount} tok` : `~${tokenCount} tok`;
+  const tpsLabel = telemetry.tokensPerSecond !== undefined ? ` ${telemetry.tokensPerSecond} tps` : "";
+  return ` [${tokenLabel}${tpsLabel}]`;
+}
+
 export class AiBundleAnalyzer {
   private readonly providerClient: AiProviderClient;
   private readonly chunkSizeBytes: number;
@@ -302,23 +312,39 @@ export class AiBundleAnalyzer {
 
       if (agent === "synthesizer") {
         const synthesized = await this.runSynthesisAgent(input, memory, this.getRetrievedContext(agent, input, memory));
-        memory[agent] = synthesized;
+        memory[agent] = synthesized.object;
+        this.emitProgress({
+          stage: "agent",
+          state: "completed",
+          message: `${agent} agent completed ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(synthesized.telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent,
+          estimatedOutputTokens: synthesized.telemetry.estimatedOutputTokens,
+          ...(synthesized.telemetry.outputTokens !== undefined ? { outputTokens: synthesized.telemetry.outputTokens } : {}),
+          ...(synthesized.telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: synthesized.telemetry.tokensPerSecond } : {}),
+        });
       } else {
         const memo = await this.runMemoAgent(agent, input, memory, this.getRetrievedContext(agent, input, memory));
-        memory[agent] = memo;
+        memory[agent] = memo.object;
+        this.emitProgress({
+          stage: "agent",
+          state: "completed",
+          message: `${agent} agent completed ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(memo.telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent,
+          estimatedOutputTokens: memo.telemetry.estimatedOutputTokens,
+          ...(memo.telemetry.outputTokens !== undefined ? { outputTokens: memo.telemetry.outputTokens } : {}),
+          ...(memo.telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: memo.telemetry.tokensPerSecond } : {}),
+        });
       }
-
-      this.emitProgress({
-        stage: "agent",
-        state: "completed",
-        message: `${agent} agent completed ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}`,
-        artifactIndex: input.artifactIndex,
-        artifactCount: input.artifactCount,
-        artifactUrl: input.artifact.url,
-        chunkIndex: input.chunkIndex + 1,
-        chunkCount: input.totalChunks,
-        agent,
-      });
     }
 
     return chunkAnalysisSchema.parse(memory.synthesizer);
@@ -332,11 +358,13 @@ export class AiBundleAnalyzer {
       chunk: string;
       chunkIndex: number;
       totalChunks: number;
+      artifactIndex: number;
+      artifactCount: number;
     },
     memory: Partial<Record<SwarmAgentName, unknown>>,
     retrievedContext: string[],
-  ): Promise<AgentMemo> {
-    return generateObjectWithTextFallback({
+  ): Promise<{ object: AgentMemo; telemetry: StreamedObjectTelemetry }> {
+    return generateObjectFromStream({
       model: this.providerClient.getModel(),
       system: getSwarmAgentPrompt(agent),
       prompt: createPromptEnvelope({
@@ -359,6 +387,22 @@ export class AiBundleAnalyzer {
           store: false,
         },
       },
+      onProgress: (telemetry) => {
+        this.emitProgress({
+          stage: "agent",
+          state: "streaming",
+          message: `${agent} agent streaming ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent,
+          estimatedOutputTokens: telemetry.estimatedOutputTokens,
+          ...(telemetry.outputTokens !== undefined ? { outputTokens: telemetry.outputTokens } : {}),
+          ...(telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: telemetry.tokensPerSecond } : {}),
+        });
+      },
     });
   }
 
@@ -369,11 +413,13 @@ export class AiBundleAnalyzer {
       chunk: string;
       chunkIndex: number;
       totalChunks: number;
+      artifactIndex: number;
+      artifactCount: number;
     },
     memory: Partial<Record<SwarmAgentName, unknown>>,
     retrievedContext: string[],
-  ): Promise<ChunkAnalysis> {
-    return generateObjectWithTextFallback({
+  ): Promise<{ object: ChunkAnalysis; telemetry: StreamedObjectTelemetry }> {
+    return generateObjectFromStream({
       model: this.providerClient.getModel(),
       system: getSwarmAgentPrompt("synthesizer"),
       prompt: createPromptEnvelope({
@@ -396,6 +442,22 @@ export class AiBundleAnalyzer {
           store: false,
         },
       },
+      onProgress: (telemetry) => {
+        this.emitProgress({
+          stage: "agent",
+          state: "streaming",
+          message: `synthesizer agent streaming ${input.artifact.url} chunk ${input.chunkIndex + 1}/${input.totalChunks}${formatAgentTelemetrySuffix(telemetry)}`,
+          artifactIndex: input.artifactIndex,
+          artifactCount: input.artifactCount,
+          artifactUrl: input.artifact.url,
+          chunkIndex: input.chunkIndex + 1,
+          chunkCount: input.totalChunks,
+          agent: "synthesizer",
+          estimatedOutputTokens: telemetry.estimatedOutputTokens,
+          ...(telemetry.outputTokens !== undefined ? { outputTokens: telemetry.outputTokens } : {}),
+          ...(telemetry.tokensPerSecond !== undefined ? { tokensPerSecond: telemetry.tokensPerSecond } : {}),
+        });
+      },
     });
   }
 
@@ -405,7 +467,7 @@ export class AiBundleAnalyzer {
     chunkAnalyses: ChunkAnalysis[],
   ): Promise<BundleAnalysis> {
     try {
-      const result = await generateObjectWithTextFallback({
+      const result = await generateObjectFromStream({
         model: this.providerClient.getModel(),
         system: [
           getGlobalMissionPrompt(),
@@ -436,7 +498,7 @@ export class AiBundleAnalyzer {
       });
 
       return finalAnalysisSchema.parse({
-        ...result,
+        ...result.object,
         artifactSummaries,
         analyzedChunkCount: chunkAnalyses.length,
       });

package/lib/ai-json.ts

@@ -1,7 +1,21 @@
-import { generateText, Output } from "ai";
+import { streamText } from "ai";
 import { z } from "zod";
 
 const jsonFencePattern = /^```(?:json)?\s*([\s\S]*?)\s*```$/i;
+const STREAM_PROGRESS_INTERVAL_MS = 750;
+const ESTIMATED_CHARS_PER_TOKEN = 4;
+
+export interface StreamedObjectTelemetry {
+  elapsedMs: number;
+  estimatedOutputTokens: number;
+  outputTokens?: number;
+  tokensPerSecond?: number;
+}
+
+export interface StreamedObjectResult<TOutput> {
+  object: TOutput;
+  telemetry: StreamedObjectTelemetry;
+}
 
 function extractBalancedJsonSlice(source: string): string | null {
   const startIndex = source.search(/[\[{]/);
@@ -15,7 +29,6 @@ function extractBalancedJsonSlice(source: string): string | null {
 
   for (let index = startIndex; index < source.length; index += 1) {
     const character = source[index];
-
     if (!character) {
       continue;
     }
@@ -53,6 +66,33 @@ function extractBalancedJsonSlice(source: string): string | null {
   return null;
 }
 
+function formatJsonSystemPrompt(system: string, contract: string): string {
+  return [
+    system,
+    "Return only one valid JSON object.",
+    "Do not wrap the JSON in markdown fences.",
+    "Do not add explanations before or after the JSON.",
+    contract,
+  ].join("\n");
+}
+
+function calculateTokensPerSecond(tokenCount: number, elapsedMs: number): number | undefined {
+  if (tokenCount <= 0 || elapsedMs < 250) {
+    return undefined;
+  }
+
+  return Number((tokenCount / (elapsedMs / 1000)).toFixed(1));
+}
+
+export function estimateTokenCountFromText(source: string): number {
+  const trimmed = source.trim();
+  if (trimmed.length === 0) {
+    return 0;
+  }
+
+  return Math.max(1, Math.ceil(trimmed.length / ESTIMATED_CHARS_PER_TOKEN));
+}
+
 export function extractJsonFromText(source: string): unknown {
   const trimmed = source.trim();
   if (!trimmed) {
@@ -74,22 +114,7 @@ export function extractJsonFromText(source: string): unknown {
   }
 }
 
-export function shouldFallbackToTextJson(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-
-  const message = error.message.toLowerCase();
-  return (
-    message.includes("responseformat") ||
-    message.includes("structured output") ||
-    message.includes("structuredoutputs") ||
-    message.includes("response did not match schema") ||
-    message.includes("no object generated")
-  );
-}
-
-export async function generateObjectWithTextFallback<TOutput>(input: {
+export async function generateObjectFromStream<TOutput>(input: {
   model: unknown;
   system: string;
   prompt: string;
@@ -97,38 +122,57 @@ export async function generateObjectWithTextFallback<TOutput>(input: {
   contract: string;
   maxRetries?: number;
   providerOptions?: Record<string, unknown>;
-}): Promise<TOutput> {
-  try {
-    const structuredResult = await generateText({
-      model: input.model as never,
-      system: input.system,
-      prompt: input.prompt,
-      output: Output.object({ schema: input.schema }),
-      maxRetries: input.maxRetries ?? 2,
-      ...(input.providerOptions !== undefined ? { providerOptions: input.providerOptions as never } : {}),
-    });
-
-    return input.schema.parse(structuredResult.output);
-  } catch (error) {
-    if (!shouldFallbackToTextJson(error)) {
-      throw error;
-    }
-  }
+  onProgress?: (telemetry: StreamedObjectTelemetry) => void;
+}): Promise<StreamedObjectResult<TOutput>> {
+  let streamedText = "";
+  const startedAt = Date.now();
+  let lastProgressAt = 0;
 
-  const textResult = await generateText({
+  const result = streamText({
     model: input.model as never,
-    system: [
-      input.system,
-      "Return only one valid JSON object.",
-      "Do not wrap the JSON in markdown fences.",
-      "Do not add explanations before or after the JSON.",
-      input.contract,
-    ].join("\n"),
+    system: formatJsonSystemPrompt(input.system, input.contract),
     prompt: input.prompt,
-    output: Output.text(),
     maxRetries: input.maxRetries ?? 2,
     ...(input.providerOptions !== undefined ? { providerOptions: input.providerOptions as never } : {}),
   });
 
-  return input.schema.parse(extractJsonFromText(textResult.output));
+  for await (const textPart of result.textStream) {
+    streamedText += textPart;
+
+    const now = Date.now();
+    if (input.onProgress !== undefined && now - lastProgressAt >= STREAM_PROGRESS_INTERVAL_MS) {
+      const estimatedOutputTokens = estimateTokenCountFromText(streamedText);
+      const tokensPerSecond = calculateTokensPerSecond(estimatedOutputTokens, now - startedAt);
+      input.onProgress({
+        elapsedMs: now - startedAt,
+        estimatedOutputTokens,
+        ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+      });
+      lastProgressAt = now;
+    }
+  }
+
+  let usage: Awaited<typeof result.usage> | undefined;
+  try {
+    usage = await result.usage;
+  } catch {
+    usage = undefined;
+  }
+  const elapsedMs = Date.now() - startedAt;
+  const estimatedOutputTokens = estimateTokenCountFromText(streamedText);
+  const outputTokens = usage?.outputTokens ?? undefined;
+  const tokensPerSecond = calculateTokensPerSecond(outputTokens ?? estimatedOutputTokens, elapsedMs);
+  const telemetry: StreamedObjectTelemetry = {
+    elapsedMs,
+    estimatedOutputTokens,
+    ...(outputTokens !== undefined ? { outputTokens } : {}),
+    ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+  };
+
+  input.onProgress?.(telemetry);
+
+  return {
+    object: input.schema.parse(extractJsonFromText(streamedText)),
+    telemetry,
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redstone-md/mapr",
-  "version": "0.0.3-alpha",
+  "version": "0.0.4-alpha",
   "type": "module",
   "description": "Bun-native CLI/TUI for reverse-engineering frontend websites, bundles, WASM, and service workers",
   "license": "SEE LICENSE IN LICENSE",