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

Phase	Description	Status	Progress
Phase 1	API Testing Foundation	Complete	101/101 SP
Phase 2	Business Rules Engine	Complete	39/39 SP
Phase 3	AI & RAG Integration	Complete	47/47 SP
Phase 4	Production Readiness	In Progress	50/85 SP

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

Outstanding Issues

Issue	Spec ID	Title	Story Points	Status
#94	SPEC0207.US01	PostgreSQL migration library	10 SP	Complete
#86	SPEC0207.US02	SQLite migration library	8 SP	Complete
#87	SPEC0207.US03	SQL Server migration library	7 SP	Complete
#89	SPEC0207.US04	Docker CI/CD pipeline	20 SP	Complete
#90	SPEC0207.US05	Authentication & authorization	25 SP	Complete
#88	SPEC0207.US06	Demo TODO application	10 SP	Pending
#92	SPEC0207.US07	RAG demo data generation	5 SP	Pending
#91	SPEC0207.US08	README documentation	5 SP	In Progress
#93	SPEC0207.US09	Roadmap improvements	5 SP	Pending
#95	SPEC0208	UserContext (UserState + Agent Loop)	13 SP	Planned
#96	SPEC0209	GraphSession + GraphSessionClient	13 SP	Planned
#97	SPEC0210	Samples App (WASM)	13 SP	Planned

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