readme

Author: KSemenenko

.github/workflows/ci.yml

@@ -9,7 +9,6 @@ on:
 env:
   DOTNET_VERSION: '10.0.x'
   SOLUTION_FILE: GraphRag.slnx
-  GRAPH_RAG_ENABLE_JANUS: 'true'
   GRAPH_RAG_ENABLE_COSMOS: 'false'
 
 jobs:

.github/workflows/release.yml

@@ -8,7 +8,6 @@ on:
 env:
   DOTNET_VERSION: '10.0.x'
   SOLUTION_FILE: GraphRag.slnx
-  GRAPH_RAG_ENABLE_JANUS: 'true'
   GRAPH_RAG_ENABLE_COSMOS: 'false'
 
 jobs:

AGENTS.md

@@ -20,6 +20,7 @@
 - All integration tests must run against real dependencies via Testcontainers modules (Neo4j, Postgres/AGE, Cosmos, Janus, etc.); do not fall back to Aspire seeding or mock containers.
 - Keep integration tests provider-agnostic; avoid adding Postgres-only scenarios when the same flow should apply to every backend.
 - Disable Cosmos DB integration tests by default; only enable the emulator when explicitly requested (set `GRAPH_RAG_ENABLE_COSMOS=true`).
+- Always enable JanusGraph integration tests: start the Janus Testcontainers module just like Neo4j/Postgres so Janus coverage runs in every `dotnet test` execution.
 
 # Conversations
 any resulting updates to agents.md should go under the section "## Rules to follow"

README.md

@@ -309,6 +309,24 @@ GraphRAG ships with a first-class Apache AGE adapter (`ManagedCode.GraphRag.Post
 
    The `AgeConnectionManager` automatically retries transient `53300: too many clients` errors (up to three exponential backoff attempts) so scopes can wait for a free slot before failing. When a scope is disposed, the underlying `IAgeClientScope` created by `IAgeClientFactory` returns its connection to the pool, keeping concurrency predictable even under heavy fan-out.
 
+   Need to tune pooling or other Npgsql settings? Set `options.ConfigureConnectionStringBuilder` / `ConfigureDataSourceBuilder` when registering the store:
+
+   ```csharp
+   builder.Services.AddPostgresGraphStore("postgres", options =>
+   {
+       options.ConnectionString = postgresConnectionString;
+       options.ConfigureConnectionStringBuilder = builder =>
+       {
+           builder.MaxPoolSize = 80;
+           builder.MinPoolSize = 40;
+       };
+       options.ConfigureDataSourceBuilder = ds =>
+       {
+           ds.EnableArrayNullabilityMode();
+       };
+   });
+   ```
+
 ### Neo4j Setup
 
 Neo4j support lives in `ManagedCode.GraphRag.Neo4j` and uses the official Bolt driver:
@@ -332,22 +350,60 @@ Neo4j support lives in `ManagedCode.GraphRag.Neo4j` and uses the official Bolt d
    ```
    The first Neo4j registration will automatically satisfy `IGraphStore`; use `GetRequiredKeyedService<IGraphStore>("neo4j")` for explicit access.
 
+   You can also override the auth token and driver config:
+
+   ```csharp
+builder.Services.AddNeo4jGraphStore("neo4j", options =>
+{
+    options.Uri = "neo4j+s://example.databases.neo4j.io";
+    options.AuthTokenFactory = _ => AuthTokens.Basic("user", "pass");
+    options.ConfigureDriver = config => config.WithMaxConnectionPoolSize(50);
+    // Or bypass everything and provide your own driver:
+    options.DriverFactory = opts => GraphDatabase.Driver(opts.Uri, AuthTokens.None);
+});
+```
+
+### JanusGraph Setup
+
+JanusGraph support (`ManagedCode.GraphRag.JanusGraph`) uses Gremlin.Net under the hood and now starts automatically in the integration fixture. Register it just like the other stores:
+
+```csharp
+builder.Services.AddJanusGraphStore("janus", options =>
+{
+    options.Host = "localhost";
+    options.Port = 8182;
+    options.ConnectionPoolSize = 16; // optional
+    options.MaxInProcessPerConnection = 32; // optional
+    options.ConfigureConnectionPool = pool =>
+    {
+        pool.MaxInProcessPerConnection = Math.Max(pool.MaxInProcessPerConnection, 8);
+    };
+});
+```
+
+By default the adapter uses a 32-connection pool with 64 in-flight requests per connection, but you can override those numbers (or mutate the underlying `ConnectionPoolSettings` directly) via the new option properties shown above.
+
 ### Azure Cosmos DB Setup
 
 The Cosmos adapter (`ManagedCode.GraphRag.CosmosDb`) targets the SQL API and works with the emulator or live accounts:
 
 1. **Provide a connection string.** Set `COSMOS_EMULATOR_CONNECTION_STRING` or configure options manually.
 2. **Register the store.**
    ```csharp
-   builder.Services.AddCosmosGraphStore("cosmos", options =>
-   {
-       options.ConnectionString = cosmosConnectionString;
-       options.DatabaseId = "GraphRagIntegration";
-       options.NodesContainerId = "nodes";
-       options.EdgesContainerId = "edges";
-   });
-   ```
-   As with other adapters, the first Cosmos store becomes the unkeyed default.
+builder.Services.AddCosmosGraphStore("cosmos", options =>
+{
+    options.ConnectionString = cosmosConnectionString;
+    options.DatabaseId = "GraphRagIntegration";
+    options.NodesContainerId = "nodes";
+    options.EdgesContainerId = "edges";
+    options.ConfigureClientOptions = clientOptions =>
+    {
+        clientOptions.GatewayModeMaxConnectionLimit = 100;
+    };
+    options.ConfigureSerializer = serializer => serializer.PropertyNamingPolicy = null;
+});
+```
+   As with other adapters, the first Cosmos store becomes the unkeyed default. If you already have a `CosmosClient`, set `options.ClientFactory` to return it and GraphRAG will reuse that instance.
 
 > **Tip:** `IGraphStore` now exposes full graph inspection and mutation helpers (`GetNodesAsync`, `GetRelationshipsAsync`, `DeleteNodesAsync`, `DeleteRelationshipsAsync`) in addition to the targeted APIs (`InitializeAsync`, `Upsert*`, `GetOutgoingRelationshipsAsync`). These use the same AGE-powered primitives, so you can inspect, prune, or export the graph without dropping down to concrete implementations.
 

src/ManagedCode.GraphRag.CosmosDb/ServiceCollectionExtensions.cs

@@ -19,18 +19,22 @@ public static IServiceCollection AddCosmosGraphStore(this IServiceCollection ser
         configure(options);
 
         services.AddKeyedSingleton<CosmosGraphStoreOptions>(key, (_, _) => options);
-        services.AddKeyedSingleton<CosmosClient>(key, (_, _) =>
+        services.AddKeyedSingleton<CosmosClient>(key, (sp, serviceKey) =>
         {
+            var opts = sp.GetRequiredKeyedService<CosmosGraphStoreOptions>(serviceKey);
             var serializerOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web)
             {
                 PropertyNamingPolicy = JsonNamingPolicy.CamelCase
             };
+            opts.ConfigureSerializer?.Invoke(serializerOptions);
+
             var cosmosOptions = new CosmosClientOptions
             {
                 Serializer = new SystemTextJsonCosmosSerializer(serializerOptions)
             };
+            opts.ConfigureClientOptions?.Invoke(cosmosOptions);
 
-            return new CosmosClient(options.ConnectionString, cosmosOptions);
+            return opts.ClientFactory?.Invoke(cosmosOptions) ?? new CosmosClient(opts.ConnectionString, cosmosOptions);
         });
         services.AddKeyedSingleton<CosmosGraphStore>(key, (sp, serviceKey) =>
         {
@@ -57,4 +61,10 @@ public sealed class CosmosGraphStoreOptions
     public string NodesContainerId { get; set; } = "nodes";
 
     public string EdgesContainerId { get; set; } = "edges";
+
+    public Action<JsonSerializerOptions>? ConfigureSerializer { get; set; }
+
+    public Action<CosmosClientOptions>? ConfigureClientOptions { get; set; }
+
+    public Func<CosmosClientOptions, CosmosClient>? ClientFactory { get; set; }
 }

src/ManagedCode.GraphRag.JanusGraph/JanusGraphGraphSONSerializerFactory.cs

@@ -0,0 +1,14 @@
+using Gremlin.Net.Structure.IO.GraphSON;
+
+namespace GraphRag.Storage.JanusGraph;
+
+internal static class JanusGraphGraphSONSerializerFactory
+{
+    private static readonly IReadOnlyDictionary<string, IGraphSONDeserializer> CustomDeserializers = new Dictionary<string, IGraphSONDeserializer>(StringComparer.Ordinal)
+    {
+        ["janusgraph:RelationIdentifier"] = new JanusGraphRelationIdentifierDeserializer()
+    };
+
+    public static GraphSON3MessageSerializer Create() =>
+        new(new GraphSON3Reader(CustomDeserializers), new GraphSON3Writer());
+}

src/ManagedCode.GraphRag.JanusGraph/JanusGraphRelationIdentifierDeserializer.cs

@@ -0,0 +1,82 @@
+using System.Text.Json;
+using Gremlin.Net.Structure.IO.GraphSON;
+
+namespace GraphRag.Storage.JanusGraph;
+
+internal sealed class JanusGraphRelationIdentifierDeserializer : IGraphSONDeserializer
+{
+    public dynamic Objectify(JsonElement graphsonObject, GraphSONReader _)
+    {
+        if (graphsonObject.ValueKind != JsonValueKind.Object)
+        {
+            return Normalize(graphsonObject) ?? string.Empty;
+        }
+
+        if (graphsonObject.TryGetProperty("relationId", out var relationId) &&
+            TryGetString(relationId, out var identifier))
+        {
+            return identifier ?? string.Empty;
+        }
+
+        var result = new Dictionary<string, object?>(StringComparer.OrdinalIgnoreCase);
+        foreach (var property in graphsonObject.EnumerateObject())
+        {
+            result[property.Name] = Normalize(property.Value);
+        }
+
+        return result;
+    }
+
+    private static bool TryGetString(JsonElement element, out string? value)
+    {
+        switch (element.ValueKind)
+        {
+            case JsonValueKind.String:
+                value = element.GetString();
+                return true;
+            case JsonValueKind.Object when element.TryGetProperty("@value", out var nested):
+                return TryGetString(nested, out value);
+            default:
+                value = null;
+                return false;
+        }
+    }
+
+    private static object? Normalize(JsonElement element)
+    {
+        return element.ValueKind switch
+        {
+            JsonValueKind.Object when element.TryGetProperty("@value", out var inner) => Normalize(inner),
+            JsonValueKind.Object => NormalizeObject(element),
+            JsonValueKind.Array => NormalizeArray(element),
+            JsonValueKind.String => element.GetString(),
+            JsonValueKind.Number => element.TryGetInt64(out var i64) ? i64 : element.GetDouble(),
+            JsonValueKind.True => true,
+            JsonValueKind.False => false,
+            JsonValueKind.Null => null,
+            _ => element.GetRawText()
+        };
+    }
+
+    private static object?[] NormalizeArray(JsonElement element)
+    {
+        var items = new List<object?>(element.GetArrayLength());
+        foreach (var child in element.EnumerateArray())
+        {
+            items.Add(Normalize(child));
+        }
+
+        return items.ToArray();
+    }
+
+    private static IDictionary<string, object?> NormalizeObject(JsonElement element)
+    {
+        var result = new Dictionary<string, object?>(StringComparer.OrdinalIgnoreCase);
+        foreach (var property in element.EnumerateObject())
+        {
+            result[property.Name] = Normalize(property.Value);
+        }
+
+        return result;
+    }
+}