LowlandTech.Graph

A flexible graph-based data system with AI-powered RAG, business rules engine, and multi-provider embedding support.

Central Thesis

LowlandTech.Graph treats tools as the only writers of reality. Agents can reason, propose, and plan, but only tool execution produces canonical, HEAD-backed facts. This enables safe agentic reasoning, replayable verification, and deterministic promotion from intent to execution.

Key loop:

• Reasoning -> Proposal -> Tool Execution -> Signed Facts -> Reasoning

Core traversal (User to WorkItems):

(User) --[has.session]--> (UserState)
  --[focuses.on]--> (WorkItem)
  --[references]--> (Graph facts / properties / edges)

UserState is a rooted, synthetic reasoning graph. It projects WorkItems from the world graph, enriches them via RAG, and emits ChangeSets at checkpoint boundaries. Tools validate and commit those ChangeSets into the world graph.

Pseudo code sketch:

// Client-side: bind a model to graph data
var client = new GraphSessionClient(apiBaseUrl);
var workItem = await client.BindAsync<WorkItemModel>(nodeId: "node:workitem:123");

workItem.Status = "InProgress";
await client.CommitAsync(workItem); // sends ShapeHash + diff to GraphSession

// Server-side: GraphSession orchestrates binding and validation
public async Task<GraphSessionResponse> BindAsync(GraphBindRequest request)
{
    var node = await _graph.GetNodeAsync(request.NodeId);
    var edges = await _graph.GetEdgesAsync(node.Id);
    var shape = await _shapeRegistry.ResolveAsync(request.ShapeHash);

    var payload = _shapeBinder.Materialize(shape, node, edges);
    return GraphSessionResponse.Success(payload);
}

public async Task<GraphStepResult> MutateAsync(GraphMutationRequest request)
{
    var step = GraphStep.From(request);
    if (!await _gateEvaluator.PassesAsync(step))
        return GraphStepResult.Fail();

    var result = await _toolExecutor.ExecuteAsync(step.ToolCall);
    return GraphStepResult.Pass(result.Edge, result.Target);
}

// Agent loop: propose tool calls from WorkItems + RAG
public async Task<AgentLoopResult> RunAsync(string query, ExecutionContext ctx)
{
    var workItems = await _graphTools.WorkItemsAsync();
    var rag = await _graphTools.SearchPropertiesAsync(query);

    ctx.Set("WorkItems", workItems);
    ctx.Set("RagEvidence", rag);

    for (var step = 0; step < _options.MaxSteps; step++)
    {
        var response = await _llm.GenerateAsync(
            prompt: BuildPrompt(query, ctx),
            tools: _toolRegistry.DescribeTools(),
            context: ctx);

        if (response.Action == "final")
            return AgentLoopResult.Final(response.Answer, ctx.Trace);

        if (response.Action == "tool")
        {
            var toolResult = await _toolRegistry.ExecuteAsync(
                response.ToolName, response.Input);

            ctx.AppendObservation(toolResult);
            continue;
        }

        break;
    }

    return AgentLoopResult.Incomplete("Step limit reached", ctx.Trace);
}

Project Status

Total Progress: 237/272 Story Points (87%)

Outstanding Issues

Features

Core Graph System

• Node & Edge Management - Full CRUD operations for graph entities
• NodeTypes & EdgeTypes - Schema-driven type system with validation
• Properties - Flexible key-value property storage
• Hierarchical Navigation - Parent-child relationships with headers

Business Rules Engine (SPEC0205)

• NCalc Integration - Mathematical and logical expression evaluation
• 12 Rule Types - Validation, calculation, constraint, and more
• Composite Rules - AND/OR/NOT rule trees
• Template Rendering - Dynamic content generation

AI & RAG System (SPEC0206)

• Vector Embeddings - PropertyVector storage with pgvector
• Multi-Provider Support - LM Studio and Ollama embedding providers
• Agent Router - Query classification (Code, Reasoning, RAG, Direct)
• Code Generation - Qwen-powered C# code generation
• Semantic Search - Vector similarity search with cosine distance

?? Authentication & Security (SPEC0207.US05) NEW

• HD Wallet Authentication - BIP39/BIP32 seed phrase-based accounts
• JWT Tokens - Secure access and refresh token system
• 2FA Support - Time-based OTP via HD wallet derivation
• ASP.NET Core Identity - Industry-standard user management
• Token Rotation - Automatic refresh token rotation for security
• Role-Based Access - Fine-grained authorization support

Quick Start

Prerequisites

• .NET 10 SDK
• PostgreSQL with pgvector extension (or use in-memory for development)
• LM Studio or Ollama (for AI features)

Installation

# Clone the repository
git clone https://github.com/lowlandtech/graph.git
cd graph

# Restore dependencies
dotnet restore

# Run the API
dotnet run --project src/api

Run Tests

dotnet test

Architecture

src/
  api/           # ASP.NET Core Web API
  lib/           # Domain entities and services
  abstractions/  # Interfaces and enums
  test/          # Integration and unit tests

Configuration

Database Connection

{
  "ConnectionStrings": {
    "GraphDatabase": "Host=localhost;Database=graph;Username=postgres;Password=..."
  }
}

AI Provider

{
  "AI": {
    "Provider": "lmstudio",
    "BaseUrl": "http://localhost:1234/v1"
  }
}

Roadmap

See ROADMAP.md for detailed implementation plans and progress tracking.

Author

wendellmva

• Website: https://lowlandtech.com/wendellmva
• Twitter: @wendellmva
• Github: @wendellmva
• LinkedIn: @wendellmva

Contributing

Contributions, issues and feature requests are welcome!

Feel free to check the issues page.

License

Copyright 2025 LowlandTech