@invana/graph-datasets 0.0.1

package/dist/usecase-demos/index.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Synthetic **LLM agent traces** — small DAGs that approximate the kind
+ * of execution graph LangSmith / Langfuse / Helicone draw for a single
+ * agent run. Each node is an `llm` call, a `tool` invocation, a
+ * `decision` branch, or a terminal `output`. Each edge is a `calls`
+ * (control-flow), `returns` (data-flow), or `branch` (decision branch).
+ *
+ * Three presets are exported so a single story can illustrate the
+ * happy path, an error+retry path, and a multi-tool branching path
+ * without re-deriving the data per render.
+ *
+ * Designed for layered DAG layouts (ELK `layered` `DOWN`); the dataset
+ * carries no positions.
+ */
+/** What the node represents in the agent's execution graph. */
+type AgentTraceNodeKind = 'llm' | 'tool' | 'decision' | 'output';
+/** Per-node execution status — drives state-config styling in the story. */
+type AgentTraceStatus = 'success' | 'error' | 'pending';
+/** What the edge represents. */
+type AgentTraceEdgeKind = 'calls' | 'returns' | 'branch';
+/** Free-form per-node data. The store keeps this opaque. */
+interface AgentTraceNodeData {
+    readonly kind: AgentTraceNodeKind;
+    readonly label: string;
+    readonly status: AgentTraceStatus;
+    readonly durationMs: number;
+    readonly tokens?: number;
+}
+/** Free-form per-edge data. */
+interface AgentTraceEdgeData {
+    readonly kind: AgentTraceEdgeKind;
+}
+interface AgentTraceNode {
+    readonly id: string;
+    readonly data: AgentTraceNodeData;
+}
+interface AgentTraceEdge {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly data: AgentTraceEdgeData;
+}
+interface AgentTraceData {
+    readonly id: string;
+    readonly name: string;
+    readonly nodes: readonly AgentTraceNode[];
+    readonly edges: readonly AgentTraceEdge[];
+}
+/** All three presets, in display order. */
+declare const agentTrace: readonly AgentTraceData[];
+
+/**
+ * Synthetic **RAG embedding explorer** dataset — ~400 2D points that
+ * imitate a UMAP / t-SNE projection of a vector index. Five thematic
+ * clusters (auth, billing, search, infra, ML) plus a sprinkling of
+ * uniform outliers, generated from a seeded RNG so the visualisation
+ * is stable across reloads.
+ *
+ * Each point carries a `cluster` id, a short `text` snippet that stands
+ * in for the chunk content, and a `source` filename. There are no edges
+ * — the story renders raw points overlaid by a
+ * `DensityContourFillLayer` to bring the cluster topology forward.
+ */
+declare const CLUSTER_NAMES: readonly ["auth", "billing", "search", "infra", "ml"];
+type RagEmbeddingsCluster = (typeof CLUSTER_NAMES)[number];
+interface RagEmbeddingsNodeData {
+    readonly cluster: RagEmbeddingsCluster;
+    readonly text: string;
+    readonly source: string;
+}
+interface RagEmbeddingsNode {
+    readonly id: string;
+    readonly position: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly data: RagEmbeddingsNodeData;
+}
+interface RagEmbeddingsData {
+    readonly nodes: readonly RagEmbeddingsNode[];
+}
+declare const ragEmbeddings: RagEmbeddingsData;
+
+/**
+ * Synthetic **microservices topology** dataset — ~20 services across a
+ * SaaS stack with call edges carrying RPS and per-edge error rates.
+ * Designed for a Datadog / Istio / Linkerd-style service-map demo.
+ *
+ * The dataset embeds one degraded service (`order-api`), one degraded
+ * downstream (`payment-service`), and one downed service
+ * (`fraud-detector`) so the story has something to flag visually
+ * without the consumer rolling a fake "simulate degradation" loop just
+ * to see the styled states.
+ */
+/** Coarse architectural tier — drives icon choice in the story. */
+type MicroservicesTier = 'gateway' | 'api' | 'logic' | 'data' | 'external';
+/** Health roll-up rendered as the node state-config name. */
+type MicroservicesHealth = 'healthy' | 'degraded' | 'down';
+interface MicroservicesNodeData {
+    readonly tier: MicroservicesTier;
+    readonly health: MicroservicesHealth;
+    /** Sustained requests-per-second at this service. */
+    readonly rps: number;
+}
+interface MicroservicesEdgeData {
+    /** Sustained requests-per-second on this dependency edge. */
+    readonly rps: number;
+    /** Fraction in `[0, 1]`. Above ~0.05 the story flags the edge. */
+    readonly errorRate: number;
+}
+interface MicroservicesNode {
+    readonly id: string;
+    readonly data: MicroservicesNodeData;
+}
+interface MicroservicesEdge {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly data: MicroservicesEdgeData;
+}
+interface MicroservicesData {
+    readonly nodes: readonly MicroservicesNode[];
+    readonly edges: readonly MicroservicesEdge[];
+}
+declare const microservices: MicroservicesData;
+
+/**
+ * Synthetic **company knowledge-graph** — entities of five kinds linked
+ * by typed relations. Modelled after Palantir / Neo4j Bloom / Diffbot
+ * entity-ontology demos so the story has a recognisable picture: five
+ * companies, the people who founded / run them, the products they ship,
+ * the cities they're based in, and the industries they operate in.
+ *
+ * The dataset is deliberately under-connected at the periphery so the
+ * "double-click to expand" interaction in the story has something
+ * meaningful to do — start with the core companies + their CEOs and
+ * unfold the products, locations, and industries by clicking.
+ */
+/** Entity kind — drives shape and palette in the story. */
+type OntologyEntityKind = 'company' | 'person' | 'product' | 'location' | 'industry';
+/** Predicate / FK label on each edge. */
+type OntologyEdgeKind = 'founded' | 'ceo_of' | 'works_at' | 'builds' | 'headquartered_in' | 'operates_in' | 'competes_with';
+interface OntologyNodeData {
+    readonly kind: OntologyEntityKind;
+    /** Human-readable display name (id stays kebab-case for stability). */
+    readonly name: string;
+}
+interface OntologyEdgeData {
+    readonly kind: OntologyEdgeKind;
+}
+interface OntologyNode {
+    readonly id: string;
+    readonly data: OntologyNodeData;
+}
+interface OntologyEdge {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly data: OntologyEdgeData;
+}
+interface OntologyData {
+    readonly nodes: readonly OntologyNode[];
+    readonly edges: readonly OntologyEdge[];
+    /** Ids that the story shows in its initial collapsed view. */
+    readonly coreIds: readonly string[];
+}
+declare const ontology: OntologyData;
+
+/**
+ * Synthetic **citation graph** — 150 papers across 5 research topics,
+ * connected by directed `paper-cites-paper` edges. Designed for a
+ * Connected-Papers / Litmaps / Elicit-style overview: density contours
+ * per topic bring the cluster topology forward, force layout pulls the
+ * dense intra-topic citation neighbourhoods together, and the inter-
+ * topic edges form the long bridges between clusters.
+ *
+ * Generation rules (seeded for snapshot stability):
+ *
+ *   - 30 papers per topic across 5 topics, years span 2018–2025.
+ *   - `citationsCount` drawn from a clipped log-normal so a handful of
+ *     hub papers dominate the visualisation.
+ *   - Each paper cites 2–4 prior papers, biased 70% intra-topic and
+ *     30% inter-topic. Within the bias bucket, targets are weighted
+ *     toward older papers with higher citation counts — i.e. crude
+ *     preferential attachment.
+ */
+declare const TOPICS: readonly ["transformers", "diffusion-models", "reinforcement-learning", "graph-neural-networks", "vision-language"];
+type CitationsTopic = (typeof TOPICS)[number];
+interface CitationsNodeData {
+    readonly topic: CitationsTopic;
+    readonly title: string;
+    readonly year: number;
+    readonly citationsCount: number;
+}
+interface CitationsEdgeData {
+    /** Reserved for future predicates (`cites`, `extends`, `refutes`, ...). */
+    readonly kind: 'cites';
+}
+interface CitationsNode {
+    readonly id: string;
+    readonly data: CitationsNodeData;
+}
+interface CitationsEdge {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    readonly data: CitationsEdgeData;
+}
+interface CitationsData {
+    readonly nodes: readonly CitationsNode[];
+    readonly edges: readonly CitationsEdge[];
+}
+declare const citations: CitationsData;
+
+/**
+ * **Cora** citation network — the canonical machine-learning paper
+ * dataset (2,708 papers across 7 subject areas, 10,556 `CITES` edges).
+ * The raw CSVs live in `./cora-dataset/{nodes,edges}.csv`; a build-time
+ * pre-strip in `scripts/prepare-cora.mjs` projects them to a compact
+ * `cora.json` (drops the 1,433-dim bag-of-words feature matrix the
+ * viewer never needs). This module imports that JSON and shapes it for
+ * `GraphLayer.setData`.
+ *
+ * Re-run the prepare script when the CSVs change:
+ *   `node scripts/prepare-cora.mjs`
+ *
+ * @example
+ * import { cora } from '@invana/graph-datasets/usecase-demos';
+ * graphLayer.setData({ nodes: cora.nodes, edges: cora.edges });
+ */
+/** Subject category — the 7 ML topics the original Cora dataset partitions papers into. */
+type CoraSubject = 'Neural_Networks' | 'Rule_Learning' | 'Reinforcement_Learning' | 'Probabilistic_Methods' | 'Theory' | 'Genetic_Algorithms' | 'Case_Based';
+interface CoraNodeData {
+    readonly subject: CoraSubject;
+}
+interface CoraNode {
+    readonly id: string;
+    readonly data: CoraNodeData;
+}
+interface CoraEdge {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+}
+interface CoraData {
+    readonly nodes: readonly CoraNode[];
+    readonly edges: readonly CoraEdge[];
+}
+declare const cora: CoraData;
+
+/**
+ * **Invana Code Knowledge Graph** — a real code-intelligence graph of the
+ * [Invana](https://github.com/invana) platform monorepo, produced by the
+ * `understand-anything` static analyser. 602 source entities (files,
+ * functions, classes, configs, docs) linked by 1,329 typed relations
+ * (`imports`, `contains`, `exports`, `calls`, `inherits`, …), partitioned
+ * into 8 architectural clusters with a 13-step guided tour.
+ *
+ * `./invana-code-kg/knowledge-graph.json` is authored **directly** in the
+ * property-graph shape this package standardises on — vertices are
+ * `{ id, label, properties }`, edges are
+ * `{ id, label, source, target, properties }` — so this module is a thin
+ * typed view over it, not a translator. The interfaces below ARE the
+ * on-disk contract; the JSON is its serialisation.
+ *
+ * `label` / `properties` don't match `@invana/graph`'s `GraphNode`
+ * (`type` / `data`) one-to-one, so a consuming story maps
+ * `label → type` and `properties → data` at `setData` time.
+ *
+ * @example
+ * import { invanaCodeKg } from '@invana/graph-datasets/usecase-demos';
+ * graphLayer.setData({
+ *   nodes: invanaCodeKg.nodes.map((n) => ({ id: n.id, type: n.label, data: n.properties })),
+ *   edges: invanaCodeKg.edges.map((e) => ({ id: e.id, source: e.source, target: e.target, type: e.label, data: e.properties })),
+ * });
+ */
+/** Vertex label — the source-entity kind. Drives shape + palette downstream. */
+type InvanaCodeNodeLabel = 'file' | 'function' | 'class' | 'config' | 'document';
+/** Analyser's coarse complexity bucket for a node. */
+type InvanaCodeComplexity = 'simple' | 'moderate' | 'complex';
+/** Edge label — the relation kind. */
+type InvanaCodeEdgeLabel = 'imports' | 'contains' | 'exports' | 'calls' | 'inherits' | 'configures' | 'depends_on' | 'documents' | 'related';
+/** Node property bag — everything that isn't `id` or `label`. */
+interface InvanaCodeNodeProperties {
+    /** Short display name (`main.tsx`, `ErrorPage`, …). `id` stays the stable path-qualified key. */
+    readonly name: string;
+    /** Repo-relative source path the entity lives in. */
+    readonly filePath: string;
+    /** One-line natural-language description from the analyser. */
+    readonly summary: string;
+    /** Free-form classification tags (`entry-point`, `react`, `error-handling`, …). */
+    readonly tags: readonly string[];
+    /** Analyser complexity bucket. */
+    readonly complexity: InvanaCodeComplexity;
+    /** `[startLine, endLine]` for function/class nodes; absent for whole-file nodes. */
+    readonly lineRange?: readonly [number, number];
+    /** Language-specific caveat the analyser flagged, when present. */
+    readonly languageNotes?: string;
+    /** Owning cluster id (from {@link InvanaCodeCluster}), or `null` when ungrouped. */
+    readonly cluster: string | null;
+}
+/** Edge property bag — relation strength + directionality metadata. */
+interface InvanaCodeEdgeProperties {
+    /** Analyser-assigned edge weight in `[0.5, 1]`. */
+    readonly weight: number;
+    /** Relation directionality. The source graph only emits `'forward'`. */
+    readonly direction: 'forward';
+}
+/** A code entity as a property-graph vertex: `{ id, label, properties }`. */
+interface InvanaCodeNode {
+    readonly id: string;
+    readonly label: InvanaCodeNodeLabel;
+    readonly properties: InvanaCodeNodeProperties;
+}
+/** A typed relation as a property-graph edge: `{ id, label, source, target, properties }`. */
+interface InvanaCodeEdge {
+    readonly id: string;
+    readonly label: InvanaCodeEdgeLabel;
+    readonly source: string;
+    readonly target: string;
+    readonly properties: InvanaCodeEdgeProperties;
+}
+/** An architectural cluster — a named group of node ids. */
+interface InvanaCodeCluster {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly nodeIds: readonly string[];
+}
+/** A guided-tour step spotlighting a set of nodes with a teaching note. */
+interface InvanaCodeTourStep {
+    readonly order: number;
+    readonly title: string;
+    readonly description: string;
+    readonly nodeIds: readonly string[];
+    readonly languageLesson?: string;
+}
+/** Project-level provenance for the analysed repository. */
+interface InvanaCodeProject {
+    readonly name: string;
+    readonly languages: readonly string[];
+    readonly frameworks: readonly string[];
+    readonly description: string;
+    readonly analyzedAt?: string;
+    readonly gitCommitHash?: string;
+}
+/** The full dataset: graph + cluster metadata + tour + provenance. */
+interface InvanaCodeKgData {
+    readonly nodes: readonly InvanaCodeNode[];
+    readonly edges: readonly InvanaCodeEdge[];
+    readonly clusters: readonly InvanaCodeCluster[];
+    readonly tour: readonly InvanaCodeTourStep[];
+    readonly project: InvanaCodeProject;
+}
+declare const invanaCodeKg: InvanaCodeKgData;
+
+export { type AgentTraceData, type AgentTraceEdge, type AgentTraceEdgeData, type AgentTraceEdgeKind, type AgentTraceNode, type AgentTraceNodeData, type AgentTraceNodeKind, type AgentTraceStatus, type CitationsData, type CitationsEdge, type CitationsEdgeData, type CitationsNode, type CitationsNodeData, type CitationsTopic, type CoraData, type CoraEdge, type CoraNode, type CoraNodeData, type CoraSubject, type InvanaCodeCluster, type InvanaCodeComplexity, type InvanaCodeEdge, type InvanaCodeEdgeLabel, type InvanaCodeEdgeProperties, type InvanaCodeKgData, type InvanaCodeNode, type InvanaCodeNodeLabel, type InvanaCodeNodeProperties, type InvanaCodeProject, type InvanaCodeTourStep, type MicroservicesData, type MicroservicesEdge, type MicroservicesEdgeData, type MicroservicesHealth, type MicroservicesNode, type MicroservicesNodeData, type MicroservicesTier, type OntologyData, type OntologyEdge, type OntologyEdgeData, type OntologyEdgeKind, type OntologyEntityKind, type OntologyNode, type OntologyNodeData, type RagEmbeddingsCluster, type RagEmbeddingsData, type RagEmbeddingsNode, type RagEmbeddingsNodeData, agentTrace, citations, cora, invanaCodeKg, microservices, ontology, ragEmbeddings };