dpth 0.1.0

package/dist/embed.js

@@ -0,0 +1,270 @@
+/**
+ * dpth.io Embedding System
+ *
+ * Everything in dpth.io can be embedded for semantic search.
+ * Find similar entities, metrics, and patterns without explicit joins.
+ *
+ * "What metrics behave like churn?"
+ * "Find entities similar to our best customers"
+ * "What patterns look like this anomaly?"
+ */
+// ─── Embedding Store ─────────────────────────────────
+const embeddings = new Map();
+// ─── Text Generation for Embedding ───────────────────
+/**
+ * Generate text representation of an entity for embedding
+ */
+export function entityToText(entity) {
+    const parts = [
+        `${entity.type}: ${entity.name}`,
+        ...entity.aliases.map(a => `also known as ${a}`),
+    ];
+    // Add key attributes
+    for (const [key, value] of Object.entries(entity.attributes)) {
+        if (typeof value.current === 'string' || typeof value.current === 'number') {
+            parts.push(`${key}: ${value.current}`);
+        }
+    }
+    // Add source information
+    const sources = entity.sources.map(s => s.sourceId).join(', ');
+    parts.push(`found in: ${sources}`);
+    return parts.join('. ');
+}
+/**
+ * Generate text representation of a metric for embedding
+ */
+export function metricToText(metric) {
+    const parts = [
+        `metric: ${metric.name}`,
+        metric.unit ? `measured in ${metric.unit}` : '',
+        `aggregated by ${metric.aggregation}`,
+    ];
+    // Add summary statistics
+    if (metric.points.length > 0) {
+        const values = metric.points.map(p => p.value);
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        const avg = values.reduce((a, b) => a + b, 0) / values.length;
+        parts.push(`ranges from ${min.toFixed(2)} to ${max.toFixed(2)}`);
+        parts.push(`average ${avg.toFixed(2)}`);
+        parts.push(`${metric.points.length} data points`);
+    }
+    return parts.filter(p => p).join('. ');
+}
+/**
+ * Generate text representation of a pattern for embedding
+ */
+export function patternToText(pattern) {
+    return `${pattern.type} pattern: ${pattern.summary}. ${pattern.explanation || ''}`;
+}
+// ─── Embedding Generation ────────────────────────────
+/**
+ * Simple bag-of-words embedding (placeholder for real embeddings)
+ *
+ * In production, this would call an embedding API (OpenAI, Cohere, etc.)
+ * or use a local model. For now, we use TF-IDF-like vectors.
+ */
+function generateEmbedding(text) {
+    // Tokenize and normalize
+    const tokens = text.toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length > 2);
+    // Create a simple hash-based embedding (384 dimensions like many real models)
+    const dimensions = 384;
+    const vector = new Array(dimensions).fill(0);
+    for (const token of tokens) {
+        // Hash token to dimension indices
+        const hash1 = simpleHash(token) % dimensions;
+        const hash2 = simpleHash(token + '_2') % dimensions;
+        const hash3 = simpleHash(token + '_3') % dimensions;
+        // Add contribution (simulating learned embeddings)
+        vector[hash1] += 1;
+        vector[hash2] += 0.5;
+        vector[hash3] += 0.25;
+    }
+    // Normalize to unit vector
+    const magnitude = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+    if (magnitude > 0) {
+        for (let i = 0; i < dimensions; i++) {
+            vector[i] /= magnitude;
+        }
+    }
+    return vector;
+}
+/**
+ * Simple string hash function
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+}
+// ─── Embedding CRUD ──────────────────────────────────
+/**
+ * Embed an entity
+ */
+export function embedEntity(entity) {
+    const text = entityToText(entity);
+    const vector = generateEmbedding(text);
+    const embedding = {
+        id: entity.id,
+        type: 'entity',
+        vector,
+        text,
+        updatedAt: new Date(),
+    };
+    embeddings.set(`entity:${entity.id}`, embedding);
+    return embedding;
+}
+/**
+ * Embed a metric
+ */
+export function embedMetric(metric) {
+    const text = metricToText(metric);
+    const vector = generateEmbedding(text);
+    const embedding = {
+        id: metric.id,
+        type: 'metric',
+        vector,
+        text,
+        updatedAt: new Date(),
+    };
+    embeddings.set(`metric:${metric.id}`, embedding);
+    return embedding;
+}
+/**
+ * Embed a pattern
+ */
+export function embedPattern(pattern) {
+    const text = patternToText(pattern);
+    const vector = generateEmbedding(text);
+    const embedding = {
+        id: pattern.id,
+        type: 'pattern',
+        vector,
+        text,
+        updatedAt: new Date(),
+    };
+    embeddings.set(`pattern:${pattern.id}`, embedding);
+    return embedding;
+}
+/**
+ * Embed arbitrary text (for queries)
+ */
+export function embedText(text) {
+    return generateEmbedding(text);
+}
+// ─── Similarity Search ───────────────────────────────
+/**
+ * Calculate cosine similarity between two vectors
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denominator === 0)
+        return 0;
+    return dotProduct / denominator;
+}
+/**
+ * Find similar items by ID
+ */
+export function findSimilar(query) {
+    const key = `${query.type}:${query.id}`;
+    const queryEmbedding = embeddings.get(key);
+    if (!queryEmbedding)
+        return [];
+    return findSimilarByVector(queryEmbedding.vector, query.type, query.minScore, query.limit, query.id // Exclude self
+    );
+}
+/**
+ * Find similar items by text query
+ */
+export function searchByText(text, type, minScore = 0.3, limit = 10) {
+    const queryVector = embedText(text);
+    return findSimilarByVector(queryVector, type, minScore, limit);
+}
+/**
+ * Find similar items by vector
+ */
+function findSimilarByVector(queryVector, type, minScore = 0.3, limit = 10, excludeId) {
+    const results = [];
+    for (const [key, embedding] of embeddings) {
+        // Filter by type if specified
+        if (type && embedding.type !== type)
+            continue;
+        // Exclude self
+        if (excludeId && embedding.id === excludeId)
+            continue;
+        const score = cosineSimilarity(queryVector, embedding.vector);
+        if (score >= minScore) {
+            results.push({
+                id: embedding.id,
+                type: embedding.type,
+                score,
+                text: embedding.text,
+            });
+        }
+    }
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+}
+/**
+ * Get embedding by key
+ */
+export function getEmbedding(type, id) {
+    return embeddings.get(`${type}:${id}`);
+}
+/**
+ * Get embedding stats
+ */
+export function getEmbeddingStats() {
+    const byType = { entity: 0, metric: 0, pattern: 0 };
+    for (const embedding of embeddings.values()) {
+        byType[embedding.type]++;
+    }
+    return {
+        total: embeddings.size,
+        byType,
+    };
+}
+/**
+ * Clear all embeddings (for testing)
+ */
+export function clearEmbeddings() {
+    embeddings.clear();
+}
+// ─── Batch Operations ────────────────────────────────
+/**
+ * Re-embed all entities (useful after model upgrade)
+ */
+export async function reembedAllEntities(entities, onProgress) {
+    for (let i = 0; i < entities.length; i++) {
+        embedEntity(entities[i]);
+        onProgress?.(i + 1, entities.length);
+    }
+}
+/**
+ * Re-embed all metrics
+ */
+export async function reembedAllMetrics(metrics, onProgress) {
+    for (let i = 0; i < metrics.length; i++) {
+        embedMetric(metrics[i]);
+        onProgress?.(i + 1, metrics.length);
+    }
+}
+//# sourceMappingURL=embed.js.map

package/dist/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"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"}

package/dist/entity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * dpth.io Entity System
+ *
+ * Unified identity across all data sources. The same person in Salesforce,
+ * Slack, GitHub, and your HR system is ONE entity in dpth.io.
+ *
+ * Key concepts:
+ * - Entity resolution: Fuzzy matching to merge identities
+ * - Source refs: Track where this entity appears
+ * - Temporal attributes: Every attribute has history
+ */
+import { Entity, EntityId, EntityType, SourceId } from './types.js';
+/**
+ * Create a new entity
+ */
+export declare function createEntity(type: EntityType, name: string, sourceId: SourceId, externalId: string, attributes?: Record<string, unknown>): Entity;
+/**
+ * Find entity by ID
+ */
+export declare function getEntity(id: EntityId): Entity | undefined;
+/**
+ * Find entity by source reference
+ */
+export declare function findEntityBySource(sourceId: SourceId, externalId: string): Entity | undefined;
+/**
+ * Update an entity's attribute (temporal update)
+ */
+export declare function updateEntityAttribute(entityId: EntityId, key: string, value: unknown, sourceId: SourceId): Entity | undefined;
+interface MatchCandidate {
+    entity: Entity;
+    score: number;
+    matchedOn: string[];
+}
+/**
+ * Find potential matches for a new record
+ */
+export declare function findMatches(type: EntityType, name: string, email?: string, aliases?: string[]): MatchCandidate[];
+/**
+ * Resolve or create: Find a matching entity or create a new one
+ */
+export declare function resolveOrCreate(type: EntityType, name: string, sourceId: SourceId, externalId: string, options?: {
+    email?: string;
+    aliases?: string[];
+    attributes?: Record<string, unknown>;
+    minConfidence?: number;
+}): {
+    entity: Entity;
+    isNew: boolean;
+    confidence: number;
+};
+/**
+ * Manually merge two entities
+ */
+export declare function mergeEntities(keepId: EntityId, mergeId: EntityId): Entity | undefined;
+/**
+ * Get all entities of a type
+ */
+export declare function getEntitiesByType(type: EntityType): Entity[];
+/**
+ * Get all entities from a source
+ */
+export declare function getEntitiesBySource(sourceId: SourceId): Entity[];
+/**
+ * Get entity attribute value at a specific point in time
+ */
+export declare function getAttributeAt<T>(entity: Entity, key: string, at: Date): T | undefined;
+/**
+ * Get entity count by type (for stats)
+ */
+export declare function getEntityStats(): Record<EntityType, number>;
+/**
+ * Clear all entities (for testing)
+ */
+export declare function clearEntities(): void;
+export {};
+//# sourceMappingURL=entity.d.ts.map

package/dist/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,MAAM,EACN,QAAQ,EACR,UAAU,EAEV,QAAQ,EAET,MAAM,YAAY,CAAC;AAoBpB;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAwCR;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAE1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG7F;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,QAAQ,GACjB,MAAM,GAAG,SAAS,CAoCpB;AAID,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,cAAc,EAAE,CA8ClB;AAkCD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAmDxD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CA2CrF;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAE5D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAIhE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,GAAG,CAAC,GAAG,SAAS,CActF;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAM3D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAGpC"}

package/dist/entity.js

@@ -0,0 +1,327 @@
+/**
+ * dpth.io Entity System
+ *
+ * Unified identity across all data sources. The same person in Salesforce,
+ * Slack, GitHub, and your HR system is ONE entity in dpth.io.
+ *
+ * Key concepts:
+ * - Entity resolution: Fuzzy matching to merge identities
+ * - Source refs: Track where this entity appears
+ * - Temporal attributes: Every attribute has history
+ */
+import crypto from 'crypto';
+// ─── Entity Store ────────────────────────────────────
+/** In-memory entity store (will be persisted later) */
+const entities = new Map();
+const sourceIndex = new Map(); // "sourceId:externalId" → entityId
+/** Generate a unique entity ID */
+function generateEntityId() {
+    return `ent_${crypto.randomBytes(12).toString('hex')}`;
+}
+/** Create index key for source lookup */
+function sourceKey(sourceId, externalId) {
+    return `${sourceId}:${externalId}`;
+}
+// ─── Entity CRUD ─────────────────────────────────────
+/**
+ * Create a new entity
+ */
+export function createEntity(type, name, sourceId, externalId, attributes) {
+    const id = generateEntityId();
+    const now = new Date();
+    const entity = {
+        id,
+        type,
+        name,
+        aliases: [],
+        sources: [{
+                sourceId,
+                externalId,
+                confidence: 1.0,
+                lastSeen: now,
+            }],
+        attributes: {},
+        createdAt: now,
+        updatedAt: now,
+    };
+    // Convert attributes to temporal values
+    if (attributes) {
+        for (const [key, value] of Object.entries(attributes)) {
+            entity.attributes[key] = {
+                current: value,
+                history: [{
+                        value,
+                        validFrom: now,
+                        validTo: null,
+                        source: sourceId,
+                    }],
+            };
+        }
+    }
+    // Store and index
+    entities.set(id, entity);
+    sourceIndex.set(sourceKey(sourceId, externalId), id);
+    return entity;
+}
+/**
+ * Find entity by ID
+ */
+export function getEntity(id) {
+    return entities.get(id);
+}
+/**
+ * Find entity by source reference
+ */
+export function findEntityBySource(sourceId, externalId) {
+    const entityId = sourceIndex.get(sourceKey(sourceId, externalId));
+    return entityId ? entities.get(entityId) : undefined;
+}
+/**
+ * Update an entity's attribute (temporal update)
+ */
+export function updateEntityAttribute(entityId, key, value, sourceId) {
+    const entity = entities.get(entityId);
+    if (!entity)
+        return undefined;
+    const now = new Date();
+    const existing = entity.attributes[key];
+    if (existing) {
+        // Close the current history entry
+        const currentHistory = existing.history.find(h => h.validTo === null);
+        if (currentHistory) {
+            currentHistory.validTo = now;
+        }
+        // Add new entry
+        existing.history.push({
+            value,
+            validFrom: now,
+            validTo: null,
+            source: sourceId,
+        });
+        existing.current = value;
+    }
+    else {
+        // New attribute
+        entity.attributes[key] = {
+            current: value,
+            history: [{
+                    value,
+                    validFrom: now,
+                    validTo: null,
+                    source: sourceId,
+                }],
+        };
+    }
+    entity.updatedAt = now;
+    return entity;
+}
+/**
+ * Find potential matches for a new record
+ */
+export function findMatches(type, name, email, aliases) {
+    const candidates = [];
+    const searchTerms = [name.toLowerCase(), ...(aliases || []).map(a => a.toLowerCase())];
+    if (email)
+        searchTerms.push(email.toLowerCase());
+    for (const entity of entities.values()) {
+        if (entity.type !== type)
+            continue;
+        const matchedOn = [];
+        let score = 0;
+        // Check name
+        const entityName = entity.name.toLowerCase();
+        if (entityName === name.toLowerCase()) {
+            score += 0.8; // Exact name match is strong signal
+            matchedOn.push('exact_name');
+        }
+        else if (fuzzyMatch(entityName, name.toLowerCase()) > 0.85) {
+            score += 0.5;
+            matchedOn.push('fuzzy_name');
+        }
+        else if (fuzzyMatch(entityName, name.toLowerCase()) > 0.7) {
+            score += 0.3;
+            matchedOn.push('partial_name');
+        }
+        // Check email attribute
+        const entityEmail = entity.attributes['email']?.current;
+        if (email && entityEmail && entityEmail.toLowerCase() === email.toLowerCase()) {
+            score += 0.9; // Email is very strong signal
+            matchedOn.push('email');
+        }
+        // Check aliases
+        for (const alias of entity.aliases) {
+            if (searchTerms.includes(alias.toLowerCase())) {
+                score += 0.3;
+                matchedOn.push('alias');
+                break;
+            }
+        }
+        if (score > 0.3) {
+            candidates.push({ entity, score: Math.min(1, score), matchedOn });
+        }
+    }
+    return candidates.sort((a, b) => b.score - a.score);
+}
+/**
+ * Simple fuzzy string matching (Levenshtein-based similarity)
+ */
+function fuzzyMatch(a, b) {
+    if (a === b)
+        return 1;
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const matrix = [];
+    for (let i = 0; i <= a.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= b.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    const distance = matrix[a.length][b.length];
+    const maxLen = Math.max(a.length, b.length);
+    return 1 - distance / maxLen;
+}
+/**
+ * Resolve or create: Find a matching entity or create a new one
+ */
+export function resolveOrCreate(type, name, sourceId, externalId, options) {
+    // First, check if we already have this exact source reference
+    const existing = findEntityBySource(sourceId, externalId);
+    if (existing) {
+        // Update last seen
+        const sourceRef = existing.sources.find(s => s.sourceId === sourceId && s.externalId === externalId);
+        if (sourceRef)
+            sourceRef.lastSeen = new Date();
+        return { entity: existing, isNew: false, confidence: 1.0 };
+    }
+    // Try to find matches
+    const minConfidence = options?.minConfidence ?? 0.7;
+    const matches = findMatches(type, name, options?.email, options?.aliases);
+    if (matches.length > 0 && matches[0].score >= minConfidence) {
+        // Merge into existing entity
+        const match = matches[0];
+        const entity = match.entity;
+        // Add source reference
+        entity.sources.push({
+            sourceId,
+            externalId,
+            confidence: match.score,
+            lastSeen: new Date(),
+        });
+        sourceIndex.set(sourceKey(sourceId, externalId), entity.id);
+        // Add aliases
+        if (!entity.aliases.includes(name) && entity.name !== name) {
+            entity.aliases.push(name);
+        }
+        // Merge attributes
+        if (options?.attributes) {
+            for (const [key, value] of Object.entries(options.attributes)) {
+                updateEntityAttribute(entity.id, key, value, sourceId);
+            }
+        }
+        entity.updatedAt = new Date();
+        return { entity, isNew: false, confidence: match.score };
+    }
+    // Create new entity
+    const entity = createEntity(type, name, sourceId, externalId, options?.attributes);
+    if (options?.aliases) {
+        entity.aliases.push(...options.aliases);
+    }
+    return { entity, isNew: true, confidence: 1.0 };
+}
+/**
+ * Manually merge two entities
+ */
+export function mergeEntities(keepId, mergeId) {
+    const keep = entities.get(keepId);
+    const merge = entities.get(mergeId);
+    if (!keep || !merge)
+        return undefined;
+    // Merge sources
+    for (const source of merge.sources) {
+        if (!keep.sources.find(s => s.sourceId === source.sourceId && s.externalId === source.externalId)) {
+            keep.sources.push(source);
+        }
+        // Update source index
+        sourceIndex.set(sourceKey(source.sourceId, source.externalId), keepId);
+    }
+    // Merge aliases
+    for (const alias of merge.aliases) {
+        if (!keep.aliases.includes(alias)) {
+            keep.aliases.push(alias);
+        }
+    }
+    if (!keep.aliases.includes(merge.name) && keep.name !== merge.name) {
+        keep.aliases.push(merge.name);
+    }
+    // Merge attributes (keep latest)
+    for (const [key, value] of Object.entries(merge.attributes)) {
+        if (!keep.attributes[key]) {
+            keep.attributes[key] = value;
+        }
+        else {
+            // Merge history
+            keep.attributes[key].history.push(...value.history);
+            // Sort by validFrom
+            keep.attributes[key].history.sort((a, b) => new Date(a.validFrom).getTime() - new Date(b.validFrom).getTime());
+        }
+    }
+    // Delete merged entity
+    entities.delete(mergeId);
+    keep.updatedAt = new Date();
+    return keep;
+}
+// ─── Query Helpers ───────────────────────────────────
+/**
+ * Get all entities of a type
+ */
+export function getEntitiesByType(type) {
+    return Array.from(entities.values()).filter(e => e.type === type);
+}
+/**
+ * Get all entities from a source
+ */
+export function getEntitiesBySource(sourceId) {
+    return Array.from(entities.values()).filter(e => e.sources.some(s => s.sourceId === sourceId));
+}
+/**
+ * Get entity attribute value at a specific point in time
+ */
+export function getAttributeAt(entity, key, at) {
+    const attr = entity.attributes[key];
+    if (!attr)
+        return undefined;
+    const timestamp = at.getTime();
+    for (const entry of attr.history) {
+        const from = new Date(entry.validFrom).getTime();
+        const to = entry.validTo ? new Date(entry.validTo).getTime() : Date.now();
+        if (timestamp >= from && timestamp <= to) {
+            return entry.value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get entity count by type (for stats)
+ */
+export function getEntityStats() {
+    const stats = {};
+    for (const entity of entities.values()) {
+        stats[entity.type] = (stats[entity.type] || 0) + 1;
+    }
+    return stats;
+}
+/**
+ * Clear all entities (for testing)
+ */
+export function clearEntities() {
+    entities.clear();
+    sourceIndex.clear();
+}
+//# sourceMappingURL=entity.js.map