@semiont/graph 0.2.28-build.40

package/README.md

@@ -0,0 +1,231 @@
+# @semiont/graph
+
+[![npm version](https://img.shields.io/npm/v/@semiont/graph)](https://www.npmjs.com/package/@semiont/graph)
+[![Tests](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml/badge.svg)](https://github.com/The-AI-Alliance/semiont/actions/workflows/package-tests.yml?query=branch%3Amain+is%3Asuccess+job%3A%22Test+graph%22)
+
+Graph database abstraction with Neo4j, Neptune, JanusGraph, and in-memory implementations.
+
+## Installation
+
+```bash
+npm install @semiont/graph
+```
+
+Then install the peer dependency for your chosen graph database:
+
+```bash
+# For Neo4j
+npm install neo4j-driver
+
+# For Neptune or JanusGraph
+npm install gremlin
+
+# For Neptune with AWS SDK
+npm install @aws-sdk/client-neptune
+
+# MemoryGraph has no dependencies
+```
+
+## Quick Start
+
+```typescript
+import { getGraphDatabase } from '@semiont/graph';
+import type { EnvironmentConfig } from '@semiont/core';
+
+const envConfig: EnvironmentConfig = {
+  services: {
+    graph: {
+      type: 'neo4j',
+      uri: 'bolt://localhost:7687',
+      username: 'neo4j',
+      password: 'password',
+      database: 'neo4j'
+    }
+  }
+};
+
+const graph = await getGraphDatabase(envConfig);
+await graph.connect();
+
+// Create a document
+const document = await graph.createDocument({
+  id: 'doc-123',
+  name: 'My Document',
+  format: 'text/plain',
+  entityTypes: ['Person', 'Organization'],
+  archived: false,
+  createdAt: new Date().toISOString(),
+  updatedAt: new Date().toISOString()
+});
+
+// Create an annotation
+const annotation = await graph.createAnnotation({
+  id: 'anno-456',
+  target: { source: 'doc-123' },
+  body: [{ value: 'Important note' }],
+  creator: 'user-123',
+  created: new Date().toISOString()
+});
+
+// Query relationships
+const annotations = await graph.getAnnotationsForDocument('doc-123');
+```
+
+## Features
+
+- 🔌 **Multiple Providers** - Neo4j, AWS Neptune, JanusGraph, In-memory
+- 🎯 **Unified Interface** - Same API across all providers
+- 📊 **W3C Compliant** - Full Web Annotation Data Model support
+- 🔄 **Event-Driven Updates** - Sync from Event Store projections
+- 🚀 **Optional Projection** - Graph is optional, core features work without it
+- 🔍 **Rich Queries** - Cross-document relationships and entity searches
+
+## Documentation
+
+- [API Reference](./docs/API.md) - Complete API documentation
+- [Architecture](./docs/ARCHITECTURE.md) - System design and principles
+- [Provider Guide](./docs/PROVIDERS.md) - Provider-specific details
+
+## Examples
+
+- [Basic Example](./examples/basic.ts) - Simple graph operations
+- [Multi-Provider](./examples/multi-provider.ts) - Switching between providers
+
+## Supported Implementations
+
+### Neo4j
+Native graph database with Cypher query language.
+
+```typescript
+const envConfig = {
+  services: {
+    graph: {
+      type: 'neo4j',
+      uri: 'bolt://localhost:7687',
+      username: 'neo4j',
+      password: 'password',
+      database: 'neo4j'
+    }
+  }
+};
+```
+
+### AWS Neptune
+Managed graph database supporting Gremlin.
+
+```typescript
+const envConfig = {
+  services: {
+    graph: {
+      type: 'neptune',
+      endpoint: 'wss://your-cluster.neptune.amazonaws.com:8182/gremlin',
+      port: 8182,
+      region: 'us-east-1'
+    }
+  }
+};
+```
+
+### JanusGraph
+Open-source distributed graph database.
+
+```typescript
+const envConfig = {
+  services: {
+    graph: {
+      type: 'janusgraph',
+      host: 'localhost',
+      port: 8182,
+      storage: 'cassandra',
+      index: 'elasticsearch'
+    }
+  }
+};
+```
+
+### MemoryGraph
+In-memory implementation for development and testing.
+
+```typescript
+const envConfig = {
+  services: {
+    graph: {
+      type: 'memory'
+    }
+  }
+};
+```
+
+## API Overview
+
+### Core Operations
+
+```typescript
+// Document operations
+await graph.createDocument(document);
+await graph.getDocument(id);
+await graph.updateDocument(id, updates);
+await graph.deleteDocument(id);
+
+// Annotation operations
+await graph.createAnnotation(annotation);
+await graph.getAnnotation(id);
+await graph.updateAnnotation(id, updates);
+await graph.deleteAnnotation(id);
+
+// Query operations
+await graph.getAnnotationsForDocument(documentId);
+await graph.findDocumentsByEntityTypes(['Person']);
+await graph.findAnnotationsByTarget(targetId);
+
+// Tag collections
+await graph.getEntityTypes();
+await graph.addEntityType('NewType');
+```
+
+## Graph as Optional Projection
+
+The graph database is designed as an **optional read-only projection**:
+
+### Works WITHOUT Graph
+✅ Viewing resources and annotations
+✅ Creating/updating/deleting annotations
+✅ Single-document workflows
+✅ Real-time SSE updates
+
+### Requires Graph
+❌ Cross-document relationship queries
+❌ Entity-based search across resources
+❌ Graph visualization
+❌ Network analysis
+
+See [Architecture Documentation](./docs/ARCHITECTURE.md) for details.
+
+## Performance
+
+| Provider | Setup | Speed | Scalability | Persistence |
+|----------|-------|-------|-------------|-------------|
+| Neo4j | Medium | Fast | High | Yes |
+| Neptune | Complex | Medium | Very High | Yes |
+| JanusGraph | Complex | Medium | Very High | Yes |
+| Memory | None | Very Fast | Low | No |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build package
+npm run build
+
+# Run tests
+npm test
+
+# Type checking
+npm run typecheck
+```
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,355 @@
+import { components, ResourceUri, AnnotationUri } from '@semiont/api-client';
+import { UpdateResourceInput, ResourceFilter, CreateAnnotationInternal, ResourceId, AnnotationCategory, AnnotationId, GraphConnection, GraphPath, EntityTypeStats, EnvironmentConfig } from '@semiont/core';
+
+type ResourceDescriptor$4 = components['schemas']['ResourceDescriptor'];
+type Annotation$4 = components['schemas']['Annotation'];
+interface GraphDatabase {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    createResource(resource: ResourceDescriptor$4): Promise<ResourceDescriptor$4>;
+    getResource(id: ResourceUri): Promise<ResourceDescriptor$4 | null>;
+    updateResource(id: ResourceUri, input: UpdateResourceInput): Promise<ResourceDescriptor$4>;
+    deleteResource(id: ResourceUri): Promise<void>;
+    listResources(filter: ResourceFilter): Promise<{
+        resources: ResourceDescriptor$4[];
+        total: number;
+    }>;
+    searchResources(query: string, limit?: number): Promise<ResourceDescriptor$4[]>;
+    createAnnotation(input: CreateAnnotationInternal): Promise<Annotation$4>;
+    getAnnotation(id: AnnotationUri): Promise<Annotation$4 | null>;
+    updateAnnotation(id: AnnotationUri, updates: Partial<Annotation$4>): Promise<Annotation$4>;
+    deleteAnnotation(id: AnnotationUri): Promise<void>;
+    listAnnotations(filter: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    }): Promise<{
+        annotations: Annotation$4[];
+        total: number;
+    }>;
+    getHighlights(resourceId: ResourceId): Promise<Annotation$4[]>;
+    resolveReference(annotationId: AnnotationId, source: ResourceId): Promise<Annotation$4>;
+    getReferences(resourceId: ResourceId): Promise<Annotation$4[]>;
+    getEntityReferences(resourceId: ResourceId, entityTypes?: string[]): Promise<Annotation$4[]>;
+    getResourceAnnotations(resourceId: ResourceId): Promise<Annotation$4[]>;
+    getResourceReferencedBy(resourceUri: ResourceUri, motivation?: string): Promise<Annotation$4[]>;
+    getResourceConnections(resourceId: ResourceId): Promise<GraphConnection[]>;
+    findPath(fromResourceId: ResourceId, toResourceId: ResourceId, maxDepth?: number): Promise<GraphPath[]>;
+    getEntityTypeStats(): Promise<EntityTypeStats[]>;
+    getStats(): Promise<{
+        resourceCount: number;
+        annotationCount: number;
+        highlightCount: number;
+        referenceCount: number;
+        entityReferenceCount: number;
+        entityTypes: Record<string, number>;
+        contentTypes: Record<string, number>;
+    }>;
+    createAnnotations(inputs: CreateAnnotationInternal[]): Promise<Annotation$4[]>;
+    resolveReferences(inputs: {
+        annotationId: AnnotationId;
+        source: ResourceId;
+    }[]): Promise<Annotation$4[]>;
+    detectAnnotations(resourceId: ResourceId): Promise<Annotation$4[]>;
+    getEntityTypes(): Promise<string[]>;
+    addEntityType(tag: string): Promise<void>;
+    addEntityTypes(tags: string[]): Promise<void>;
+    generateId(): string;
+    clearDatabase(): Promise<void>;
+}
+
+type GraphDatabaseType = 'neptune' | 'neo4j' | 'janusgraph' | 'memory';
+interface GraphDatabaseConfig {
+    type: GraphDatabaseType;
+    neptuneEndpoint?: string;
+    neptunePort?: number;
+    neptuneRegion?: string;
+    neo4jUri?: string;
+    neo4jUsername?: string;
+    neo4jPassword?: string;
+    neo4jDatabase?: string;
+    janusHost?: string;
+    janusPort?: number;
+    janusStorageBackend?: 'cassandra' | 'hbase' | 'berkeleydb';
+    janusIndexBackend?: 'elasticsearch' | 'solr' | 'lucene';
+}
+declare function createGraphDatabase(config: GraphDatabaseConfig, envConfig: EnvironmentConfig): GraphDatabase;
+declare function getGraphDatabase(envConfig: EnvironmentConfig): Promise<GraphDatabase>;
+declare function closeGraphDatabase(): Promise<void>;
+
+type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
+type Annotation$3 = components['schemas']['Annotation'];
+declare class Neo4jGraphDatabase implements GraphDatabase {
+    private driver;
+    private connected;
+    private config;
+    private entityTypesCollection;
+    constructor(config?: {
+        uri?: string;
+        username?: string;
+        password?: string;
+        database?: string;
+    });
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    private getSession;
+    private ensureSchemaExists;
+    createResource(resource: ResourceDescriptor$3): Promise<ResourceDescriptor$3>;
+    getResource(id: ResourceUri): Promise<ResourceDescriptor$3 | null>;
+    updateResource(id: ResourceUri, input: UpdateResourceInput): Promise<ResourceDescriptor$3>;
+    deleteResource(id: ResourceUri): Promise<void>;
+    listResources(filter: ResourceFilter): Promise<{
+        resources: ResourceDescriptor$3[];
+        total: number;
+    }>;
+    searchResources(query: string, limit?: number): Promise<ResourceDescriptor$3[]>;
+    createAnnotation(input: CreateAnnotationInternal): Promise<Annotation$3>;
+    getAnnotation(id: AnnotationUri): Promise<Annotation$3 | null>;
+    updateAnnotation(id: AnnotationUri, updates: Partial<Annotation$3>): Promise<Annotation$3>;
+    deleteAnnotation(id: AnnotationUri): Promise<void>;
+    listAnnotations(filter: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    }): Promise<{
+        annotations: Annotation$3[];
+        total: number;
+    }>;
+    getHighlights(resourceId: ResourceId): Promise<Annotation$3[]>;
+    resolveReference(annotationId: AnnotationId, source: ResourceId): Promise<Annotation$3>;
+    getReferences(resourceId: ResourceId): Promise<Annotation$3[]>;
+    getEntityReferences(resourceId: ResourceId, entityTypes?: string[]): Promise<Annotation$3[]>;
+    getResourceAnnotations(resourceId: ResourceId): Promise<Annotation$3[]>;
+    getResourceReferencedBy(resourceUri: ResourceUri, motivation?: string): Promise<Annotation$3[]>;
+    getResourceConnections(resourceId: ResourceId): Promise<GraphConnection[]>;
+    findPath(fromResourceId: string, toResourceId: string, maxDepth?: number): Promise<GraphPath[]>;
+    getEntityTypeStats(): Promise<EntityTypeStats[]>;
+    getStats(): Promise<{
+        resourceCount: number;
+        annotationCount: number;
+        highlightCount: number;
+        referenceCount: number;
+        entityReferenceCount: number;
+        entityTypes: Record<string, number>;
+        contentTypes: Record<string, number>;
+    }>;
+    createAnnotations(inputs: CreateAnnotationInternal[]): Promise<Annotation$3[]>;
+    resolveReferences(inputs: {
+        annotationId: AnnotationId;
+        source: ResourceId;
+    }[]): Promise<Annotation$3[]>;
+    detectAnnotations(_resourceId: ResourceId): Promise<Annotation$3[]>;
+    getEntityTypes(): Promise<string[]>;
+    addEntityType(tag: string): Promise<void>;
+    addEntityTypes(tags: string[]): Promise<void>;
+    private initializeTagCollections;
+    private persistTagCollection;
+    generateId(): string;
+    clearDatabase(): Promise<void>;
+    private parseResourceNode;
+    private parseAnnotationNode;
+}
+
+type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
+type Annotation$2 = components['schemas']['Annotation'];
+declare class NeptuneGraphDatabase implements GraphDatabase {
+    private connected;
+    private neptuneEndpoint?;
+    private neptunePort;
+    private region?;
+    private g;
+    private connection;
+    private fetchAnnotationsWithEntityTypes;
+    constructor(config?: {
+        endpoint?: string;
+        port?: number;
+        region?: string;
+    });
+    private discoverNeptuneEndpoint;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    createResource(resource: ResourceDescriptor$2): Promise<ResourceDescriptor$2>;
+    getResource(id: ResourceUri): Promise<ResourceDescriptor$2 | null>;
+    updateResource(id: ResourceUri, input: UpdateResourceInput): Promise<ResourceDescriptor$2>;
+    deleteResource(id: ResourceUri): Promise<void>;
+    listResources(filter: ResourceFilter): Promise<{
+        resources: ResourceDescriptor$2[];
+        total: number;
+    }>;
+    searchResources(query: string, limit?: number): Promise<ResourceDescriptor$2[]>;
+    createAnnotation(input: CreateAnnotationInternal): Promise<Annotation$2>;
+    getAnnotation(id: AnnotationUri): Promise<Annotation$2 | null>;
+    updateAnnotation(id: AnnotationUri, updates: Partial<Annotation$2>): Promise<Annotation$2>;
+    deleteAnnotation(id: AnnotationUri): Promise<void>;
+    listAnnotations(filter: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    }): Promise<{
+        annotations: Annotation$2[];
+        total: number;
+    }>;
+    getHighlights(resourceId: ResourceId): Promise<Annotation$2[]>;
+    resolveReference(annotationId: AnnotationId, source: ResourceId): Promise<Annotation$2>;
+    getReferences(resourceId: ResourceId): Promise<Annotation$2[]>;
+    getEntityReferences(resourceId: ResourceId, entityTypes?: string[]): Promise<Annotation$2[]>;
+    getResourceAnnotations(resourceId: ResourceId): Promise<Annotation$2[]>;
+    getResourceReferencedBy(resourceUri: ResourceUri, _motivation?: string): Promise<Annotation$2[]>;
+    getResourceConnections(resourceId: ResourceId): Promise<GraphConnection[]>;
+    findPath(fromResourceId: string, toResourceId: string, maxDepth?: number): Promise<GraphPath[]>;
+    getEntityTypeStats(): Promise<EntityTypeStats[]>;
+    getStats(): Promise<{
+        resourceCount: number;
+        annotationCount: number;
+        highlightCount: number;
+        referenceCount: number;
+        entityReferenceCount: number;
+        entityTypes: Record<string, number>;
+        contentTypes: Record<string, number>;
+    }>;
+    createAnnotations(inputs: CreateAnnotationInternal[]): Promise<Annotation$2[]>;
+    resolveReferences(inputs: {
+        annotationId: AnnotationId;
+        source: ResourceId;
+    }[]): Promise<Annotation$2[]>;
+    detectAnnotations(_resourceId: ResourceId): Promise<Annotation$2[]>;
+    private entityTypesCollection;
+    getEntityTypes(): Promise<string[]>;
+    addEntityType(tag: string): Promise<void>;
+    addEntityTypes(tags: string[]): Promise<void>;
+    private initializeTagCollections;
+    generateId(): string;
+    clearDatabase(): Promise<void>;
+}
+
+type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
+type Annotation$1 = components['schemas']['Annotation'];
+declare class JanusGraphDatabase implements GraphDatabase {
+    private graphConfig;
+    private envConfig;
+    private connected;
+    private connection;
+    private g;
+    private entityTypesCollection;
+    constructor(graphConfig: {
+        host?: string;
+        port?: number;
+        storageBackend?: 'cassandra' | 'hbase' | 'berkeleydb';
+        indexBackend?: 'elasticsearch' | 'solr' | 'lucene';
+    }, envConfig: EnvironmentConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    private initializeSchema;
+    private vertexToResource;
+    private getPropertyValue;
+    private fetchAnnotationsWithEntityTypes;
+    private vertexToAnnotation;
+    createResource(resource: ResourceDescriptor$1): Promise<ResourceDescriptor$1>;
+    getResource(id: ResourceUri): Promise<ResourceDescriptor$1 | null>;
+    updateResource(id: ResourceUri, input: UpdateResourceInput): Promise<ResourceDescriptor$1>;
+    deleteResource(id: ResourceUri): Promise<void>;
+    listResources(filter: ResourceFilter): Promise<{
+        resources: ResourceDescriptor$1[];
+        total: number;
+    }>;
+    searchResources(query: string, limit?: number): Promise<ResourceDescriptor$1[]>;
+    createAnnotation(input: CreateAnnotationInternal): Promise<Annotation$1>;
+    getAnnotation(id: AnnotationUri): Promise<Annotation$1 | null>;
+    updateAnnotation(id: AnnotationUri, updates: Partial<Annotation$1>): Promise<Annotation$1>;
+    deleteAnnotation(id: AnnotationUri): Promise<void>;
+    listAnnotations(filter: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    }): Promise<{
+        annotations: Annotation$1[];
+        total: number;
+    }>;
+    getHighlights(resourceId: ResourceId): Promise<Annotation$1[]>;
+    resolveReference(annotationId: AnnotationId, source: ResourceId): Promise<Annotation$1>;
+    getReferences(resourceId: ResourceId): Promise<Annotation$1[]>;
+    getEntityReferences(resourceId: ResourceId, entityTypes?: string[]): Promise<Annotation$1[]>;
+    getResourceAnnotations(resourceId: ResourceId): Promise<Annotation$1[]>;
+    getResourceReferencedBy(resourceUri: ResourceUri, _motivation?: string): Promise<Annotation$1[]>;
+    getResourceConnections(resourceId: ResourceId): Promise<GraphConnection[]>;
+    findPath(_fromResourceId: string, _toResourceId: string, _maxDepth?: number): Promise<GraphPath[]>;
+    getEntityTypeStats(): Promise<EntityTypeStats[]>;
+    getStats(): Promise<any>;
+    createAnnotations(inputs: CreateAnnotationInternal[]): Promise<Annotation$1[]>;
+    resolveReferences(inputs: Array<{
+        annotationId: AnnotationId;
+        source: ResourceId;
+    }>): Promise<Annotation$1[]>;
+    detectAnnotations(_resourceId: ResourceId): Promise<Annotation$1[]>;
+    getEntityTypes(): Promise<string[]>;
+    addEntityType(tag: string): Promise<void>;
+    addEntityTypes(tags: string[]): Promise<void>;
+    private initializeTagCollections;
+    generateId(): string;
+    clearDatabase(): Promise<void>;
+}
+
+type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
+type Annotation = components['schemas']['Annotation'];
+declare class MemoryGraphDatabase implements GraphDatabase {
+    private connected;
+    private resources;
+    private annotations;
+    constructor(config?: any);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    createResource(resource: ResourceDescriptor): Promise<ResourceDescriptor>;
+    getResource(id: ResourceUri): Promise<ResourceDescriptor | null>;
+    updateResource(id: ResourceUri, input: UpdateResourceInput): Promise<ResourceDescriptor>;
+    deleteResource(id: ResourceUri): Promise<void>;
+    listResources(filter: ResourceFilter): Promise<{
+        resources: ResourceDescriptor[];
+        total: number;
+    }>;
+    searchResources(query: string, limit?: number): Promise<ResourceDescriptor[]>;
+    createAnnotation(input: CreateAnnotationInternal): Promise<Annotation>;
+    getAnnotation(id: AnnotationUri): Promise<Annotation | null>;
+    updateAnnotation(id: AnnotationUri, updates: Partial<Annotation>): Promise<Annotation>;
+    deleteAnnotation(id: AnnotationUri): Promise<void>;
+    listAnnotations(filter: {
+        resourceId?: ResourceId;
+        type?: AnnotationCategory;
+    }): Promise<{
+        annotations: Annotation[];
+        total: number;
+    }>;
+    getHighlights(resourceId: ResourceId): Promise<Annotation[]>;
+    resolveReference(annotationId: AnnotationId, source: ResourceId): Promise<Annotation>;
+    getReferences(resourceId: ResourceId): Promise<Annotation[]>;
+    getEntityReferences(resourceId: ResourceId, entityTypes?: string[]): Promise<Annotation[]>;
+    getResourceAnnotations(resourceId: ResourceId): Promise<Annotation[]>;
+    getResourceReferencedBy(resourceUri: ResourceUri, _motivation?: string): Promise<Annotation[]>;
+    getResourceConnections(resourceId: ResourceId): Promise<GraphConnection[]>;
+    findPath(fromResourceId: string, toResourceId: string, maxDepth?: number): Promise<GraphPath[]>;
+    getEntityTypeStats(): Promise<EntityTypeStats[]>;
+    getStats(): Promise<{
+        resourceCount: number;
+        annotationCount: number;
+        highlightCount: number;
+        referenceCount: number;
+        entityReferenceCount: number;
+        entityTypes: Record<string, number>;
+        contentTypes: Record<string, number>;
+    }>;
+    createAnnotations(inputs: CreateAnnotationInternal[]): Promise<Annotation[]>;
+    resolveReferences(inputs: {
+        annotationId: AnnotationId;
+        source: ResourceId;
+    }[]): Promise<Annotation[]>;
+    detectAnnotations(_resourceId: ResourceId): Promise<Annotation[]>;
+    private entityTypesCollection;
+    getEntityTypes(): Promise<string[]>;
+    addEntityType(tag: string): Promise<void>;
+    addEntityTypes(tags: string[]): Promise<void>;
+    private initializeTagCollections;
+    generateId(): string;
+    clearDatabase(): Promise<void>;
+}
+
+export { type GraphDatabase, JanusGraphDatabase, MemoryGraphDatabase, Neo4jGraphDatabase, NeptuneGraphDatabase, closeGraphDatabase, createGraphDatabase, getGraphDatabase };