convez.ai
MCP ServerDados & AnalyticsAvançado
kherrera6219

DataLogicEngine

kherrera6219/DataLogicEngine

IA empresarial explicável com orquestração multi-agente e auditoria completa

Ver no GitHub
BomPluginScore · de 0 a 100

Plataforma de IA empresarial construída sobre um Grafo de Conhecimento Universal (UKG) com orquestração multi-agente, raciocínio explicável e auditoria completa. Implementa um Framework de Conhecimento de 17 Eixos e um Motor da Verdade de 10 Camadas para garantir rastreabilidade total das decisões de IA em ambientes de compliance e governança.

Instalação

$npx convez-ai kherrera6219/DataLogicEngine

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
1
Saúde
100%
Último commit
há 2 dias
Versão
—
Issues abertas
2
Contribuidores
3

Casos de uso

  • Sistemas de IA com rastreabilidade regulatória (EU AI Act)
  • Orquestração de agentes com governança e compliance
  • Análise de conhecimento estruturado via grafos com GraphRAG

Veredito

Plataforma robusta para enterprise com foco real em explicabilidade e auditoria, não apenas em performance. A implementação de 120+ algoritmos de conhecimento e governança estruturada a diferencia de LLM chains tradicionais, mas exige expertise técnica significativa e infraestrutura dedicada para produção.

README

A tradução para o português deste README ainda está na fila.

DataLogicEngine

Enterprise AI orchestration, governed LLM routing, and knowledge graph reasoning in one deployable platform.

CI Security Deploy Python Node License

DataLogicEngine (DLE) is a local-first Enterprise AI Platform built around the Universal Knowledge Graph (UKG).

Unlike traditional AI applications that operate as black boxes, DLE provides explainable reasoning, multi-agent orchestration, GraphRAG retrieval, governance controls, and complete audit traceability.

Designed for enterprise, government, compliance, cybersecurity, acquisition, and research environments, every AI decision can be traced through evidence sources, personas, reasoning stages, validation checkpoints, and immutable audit records compliant with EU AI Act Article 53.

Current Status: Feature Complete (Local-First Edition)

Major Systems Completed:

  • Universal Knowledge Graph (UKG)
  • 17-Axis Knowledge Framework
  • 10-Layer Truth Engine
  • 12-Step Refinement Workflow
  • Knowledge Algorithm Framework (120+ KAs)
  • Multi-Agent Orchestration
  • GraphRAG Integration
  • Knowledge Ingestion Pipeline
  • Trace Viewer
  • MCP Integration Framework
  • Local Database Lifecycle Management
  • Enterprise Audit & Governance Framework
  • 6-Tier Local LLM Chain (Ollama T0–T3, no API key required)

Current Focus:

  • Accessibility validation (NVDA)
  • Production code signing
  • Release evidence package
  • Public architecture assets
  • Expanded integration benchmarks
  • Public release readiness

What Makes DataLogicEngine Different?

Most AI applications answer questions.

DataLogicEngine explains how answers were produced.

Core Differentiators

Universal Knowledge Graph (UKG)

A structured knowledge system designed to organize information, expertise, regulations, compliance requirements, risk factors, locations, time contexts, and reasoning workflows into a unified framework accessible to human operators and AI agents.

17-Axis Knowledge Framework

A multidimensional coordinate system that maps every request across knowledge domains, industries, regulatory frameworks, compliance requirements, expertise models, geography, temporal context, risk profiles, and governance policies.

10-Layer Truth Engine

A progressive reasoning architecture that combines retrieval, validation, simulation, planning, trust analysis, safety controls, and audit generation into a governed AI workflow.

12-Step Refinement Workflow

A structured reasoning improvement pipeline that continuously validates, refines, audits, and strengthens outputs before release.

Knowledge Algorithm Framework

More than 120 specialized Knowledge Algorithms (KAs) provide modular capabilities for planning, validation, compliance analysis, contradiction detection, risk assessment, reasoning control, governance policy enforcement, and audit trace generation.

Explainable AI

Every response can be traced through:

  • Evidence sources
  • Personas
  • Knowledge Algorithms
  • Validation checkpoints
  • Refinement stages
  • Governance policies
  • Audit records

Local-First Architecture with Built-In Local LLMs

Supports disconnected, air-gapped, enterprise, government, and workstation deployments without requiring external cloud infrastructure.

A built-in 6-tier LLM escalation chain runs entirely on-device via Ollama — no API key required. Local models (T0 gemma4:latest → T1 gemma4:12b → T2 qwen3:14b → T3 devstral-small-2:latest) handle the full reasoning workload by default. Cloud providers (T4 Gemini Flash 3.5, T5 GPT-5.5) auto-unlock only when a key is saved in Settings.

Model Context Protocol (MCP)

Native MCP support enables integration with tools, resources, external agent systems, subscriptions, and dynamic plugin architectures.

Roadmap

Release Readiness:

  • Complete NVDA accessibility validation
  • Production code-signing pipeline
  • Final release evidence package
  • Public architecture diagrams and assets
  • Expanded integration and performance benchmarking

Enterprise Enhancements:

  • Advanced policy-as-code governance
  • Expanded multi-tenant controls
  • Enhanced cost and usage analytics
  • Human feedback and review workflows
  • Advanced persona orchestration strategies

Platform Evolution:

  • Local SLM optimization for lower reasoning tiers — Delivered: 6-tier Ollama chain (T0 gemma4:latest → T3 devstral-small-2:latest)
  • Expanded GraphRAG retrieval capabilities
  • Enterprise deployment automation
  • Additional knowledge ingestion connectors
  • Advanced knowledge graph learning and adaptation

Recently Completed:

  • ✅ Local-first database lifecycle management
  • ✅ GraphRAG integration
  • ✅ Trace Viewer implementation
  • ✅ PDF and DOCX ingestion support
  • ✅ Async ingestion workflows
  • ✅ SQL to Neo4j synchronization
  • ✅ Advanced MCP integration framework
  • ✅ Real-time trace streaming
  • ✅ Automated documentation validation
  • ✅ Portable workstation deployment stack
  • ✅ Enterprise audit traceability framework
  • ✅ Knowledge Algorithm expansion and validation
  • ✅ Truth Engine release readiness improvements
  • ✅ 6-tier local-to-cloud LLM escalation chain (Ollama T0–T3, Gemini Flash T4, GPT-5.5 T5)
  • ✅ OllamaProvider SDK with health check, streaming, and JSON generation
  • ✅ Cloud escalation auto-unlock when Google/OpenAI API key is saved in Settings

See TODO.md for the canonical backlog and release-readiness work items.

Recommended architecture asset path: docs/assets/readme/architecture-overview.png. Add a dark-mode-safe PNG/SVG export when publishing visual docs.

Quick Links

Quickstart

Run the full local stack with Docker:

git clone https://github.com/kherrera6219/DataLogicEngine.git
cd DataLogicEngine
cp .env.template .env
docker compose up --build

Open:

ServiceURL
Web consolehttp://localhost:3000
Backend APIhttp://localhost:5000
Health probehttp://localhost:5000/health
Metricshttp://localhost:5000/metrics
Swagger UIhttp://localhost:5000/api/docs

Minimal API call:

curl http://localhost:5000/health

Contents

Why DataLogicEngine

DataLogicEngine is designed for teams that need AI workflows to be explainable, inspectable, and operable in regulated environments.

CapabilityWhat it provides
LLM gatewayMulti-provider routing with a 6-tier auto-escalation chain: local Ollama models (T0–T3, no API key required) through cloud providers (T4 Gemini Flash 3.5, T5 GPT-5.5). Includes retries, circuit-breaker behavior, cost tracking, and audit metadata.
Knowledge graphStructured graph model with sectors, domains, pillars, knowledge nodes, edges, and 17-axis reasoning support.
Traceable reasoningRuns, traces, stage timing, persona context, and evidence references for audit reconstruction.
GovernanceRBAC, MFA support, CSRF controls, CORS policy enforcement, prompt-injection checks, request limits, and immutable audit patterns.
Local-first distributionBrowser deployment plus Electron/NSIS Windows packaging for workstation and constrained-network scenarios.
Production operationsDocker Compose, cloud Dockerfile, health/readiness probes, metrics endpoint, Sentry integration, and CI/security workflows.

Architecture

flowchart LR
  Client["Web console / API client"] --> Frontend["Next.js frontend"]
  Frontend --> API["Flask API"]
  API --> Auth["Auth, RBAC, CSRF, rate limits"]
  API --> Gateway["LLM Gateway"]
  API --> Graph["Knowledge Graph APIs"]
  API --> Truth["Truth Engine and tracing"]
  Gateway --> Providers["OpenAI / Anthropic / Azure / Google / Ollama (local)"]
  Graph --> Postgres["PostgreSQL"]
  Graph --> Neo4j["Neo4j"]
  API --> Redis["Redis cache and rate limit storage"]
  API --> ObjectStore["S3-compatible object storage"]
  API --> Metrics["/health /ready /metrics"]

Runtime Components

LayerComponentsNotes
FrontendNext.js 16, React 18, Electron 40Web console, desktop shell, graph visualization, admin surfaces.
BackendFlask 3.1, SQLAlchemy, Socket.IOAPI routing, auth, gateway orchestration, audit, tracing.
DataPostgreSQL 15+, Neo4j 5+, Redis 7+, MinIORelational state, graph state, cache/rate limits, object storage.
AIOpenAI, Anthropic, Azure OpenAI, Google/Gemini, Ollama (local)6-tier auto-escalation: T0–T3 route to local Ollama models (no key needed); T4–T5 route to cloud when a key is saved. Provider keys resolved at runtime from environment or configured provider records.
QualityPytest, Ruff, Vitest, Playwright, GitHub ActionsCI includes backend, frontend, governance, security, deploy, and Windows packaging checks.

Installation

Prerequisites

ToolVersionPurpose
Python3.11+Backend runtime and tests
Node.js24+Frontend and Electron tooling
DockerCurrent stableLocal full-stack development
PostgreSQL15+Production relational store
Redis7+Cache, rate limiting, async support
Neo4j5+Knowledge graph storage
OllamaCurrent stableLocal LLM inference — required for T0–T3 chain (no API key needed)

Backend Development

Windows:

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt
copy .env.template .env
python app.py

macOS/Linux:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
cp .env.template .env
python app.py

Frontend Development

cd frontend
npm ci
npm run dev

Local Mode (no Docker, no cloud databases)

For workstation development without Docker, the setup script downloads and installs portable PostgreSQL, Redis, and Neo4j binaries locally and the app manages their lifecycle automatically:

# Install portable database binaries (one-time)
python scripts/setup_local_databases.py --all

# Seed Neo4j with UKG pillar taxonomy
python scripts/seed_neo4j.py

# Run database migrations
flask db upgrade

# Start the backend (databases auto-start on app launch)
python app.py

Verify all services are reachable:

python scripts/setup_local_databases.py --verify

Desktop Build

npm --prefix frontend run electron:dist

Installer artifacts are copied to the repository root as a single canonical setup executable:

  • DataLogicEngine Setup Latest.exe
  • matching .sha256 and .blockmap files

Model Provider Setup

DataLogicEngine routes queries through a 6-tier escalation chain, but the full chain is not required. The app works with any combination of tiers — just one local model, just one cloud provider, a mix of both, or the full chain. Configure only what you have available.

TierModelProviderRequires
T0gemma4:latestOllama (local)Ollama installed + model pulled
T1gemma4:12bOllama (local)Ollama installed + model pulled
T2qwen3:14bOllama (local)Ollama installed + model pulled
T3devstral-small-2:latestOllama (local)Ollama installed + model pulled
T4gemini-3.5-flashGoogle / GeminiGoogle API key
T5gpt-5.5OpenAIOpenAI API key

Local models via Ollama (T0–T3)

Ollama runs models on-device with no API key or cloud account required.

Install Ollama

Download and run the installer from ollama.com/download (Windows, macOS, and Linux). Ollama starts as a background service on http://localhost:11434.

Pull models — pull only the tiers you want to use:

ollama pull gemma4:latest            # T0 — ultra-light, ~1s responses
ollama pull gemma4:12b               # T1 — local primary reasoning
ollama pull qwen3:14b                # T2 — extended reasoning (thinking model)
ollama pull devstral-small-2:latest  # T3 — code and structured output

Hardware note: gemma4:12b (T1) and qwen3:14b (T2) are thinking models and perform best with 8 GB+ VRAM. gemma4:latest (T0) and devstral-small-2:latest (T3) are lighter and run on 4–6 GB VRAM or CPU offload.

Verify:

ollama list                # shows pulled models
curl http://localhost:11434  # returns: Ollama is running

Set OLLAMA_BASE_URL in .env only if Ollama is on a non-default host or port.

Cloud providers (T4 and T5, optional)

Cloud tiers are optional and unlock automatically when a key is saved in Settings → AI/Model. No restart required.

T4 — Google Gemini Flash 3.5

  1. Get an API key at aistudio.google.com (free tier available).
  2. In the app: Settings → AI/Model → Provider: google → paste key → Save.
  3. Or set GOOGLE_API_KEY (or GEMINI_API_KEY) in .env before starting the backend.

T5 — OpenAI GPT-5.5

  1. Get an API key at platform.openai.com.
  2. In the app: Settings → AI/Model → Provider: openai → paste key → Save.
  3. Or set OPENAI_API_KEY in .env before starting the backend.

Once a cloud key is saved, the gateway's cloud escalation gate opens and complex queries will route to T4/T5 automatically. The Dashboard LLM Escalation Chain card shows which tiers are currently unlocked.

Configuration

Copy .env.template to .env and set values for your deployment target.

Required Production Variables

VariableRequiredDescription
FLASK_ENVYesUse production for deployed environments.
SECRET_KEYYesFlask session secret. Generate a unique 64+ character value.
JWT_SECRET_KEYYesJWT signing secret. Generate a unique 64+ character value.
SESSION_SECRETYesSession signing secret used by runtime checks.
DATABASE_URLYesSQLAlchemy database URL. PostgreSQL is recommended for production.
CORS_ORIGINSYesComma-separated allowed browser origins. Do not use * in production.
ADMIN_USERNAMEInitial setupInitial administrative username.
ADMIN_PASSWORDInitial setupStrong initial password. Rotate after first login.
ADMIN_EMAILInitial setupInitial administrator email.

Provider and Integration Variables

VariableDescription
OPENAI_API_KEYOpenAI provider key.
ANTHROPIC_API_KEYAnthropic provider key.
AZURE_OPENAI_ENDPOINTAzure OpenAI endpoint URL.
AZURE_OPENAI_API_KEYAzure OpenAI provider key.
GOOGLE_API_KEY / GEMINI_API_KEYGoogle/Gemini provider key. Enables T4 (Gemini Flash 3.5) cloud escalation.
OLLAMA_BASE_URLOptional. Ollama endpoint (default: http://localhost:11434). Required when Ollama is on a non-default host/port. T0–T3 local inference requires no API key.
SENTRY_DSNEnables crash reporting when configured.
SENTRY_TRACES_SAMPLE_RATEDistributed trace sampling rate. Default: 0.1.
SENTRY_PROFILES_SAMPLE_RATEProfiling sample rate. Default: 0.1.

Data Services

VariableDefault / ExampleDescription
REDIS_URLredis://localhost:6379/0Cache and runtime coordination.
RATELIMIT_STORAGE_URIredis://localhost:6379Flask-Limiter storage backend.
NEO4J_URIbolt://localhost:7687Neo4j Bolt endpoint. Standard Neo4j Bolt port.
NEO4J_USERneo4jNeo4j username.
NEO4J_PASSWORDunsetNeo4j password.
OBJECT_ENDPOINT_URLhttp://localhost:9000S3-compatible object storage endpoint.
OBJECT_ACCESS_KEYunsetObject storage access key.
OBJECT_SECRET_KEYunsetObject storage secret key.
OBJECT_BUCKETdatalogicObject storage bucket.

API Examples

Base URLs:

EnvironmentBase URL
Local backendhttp://localhost:5000
Versioned APIhttp://localhost:5000/api/v1
Productionhttps://your-domain.example/api/v1

Health and Readiness

curl http://localhost:5000/health
curl http://localhost:5000/live
curl http://localhost:5000/ready

Authentication

curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "operator@example.com",
    "password": "replace-with-a-secret"
  }'

API key authentication is also supported for programmatic access. Generate a key via the admin interface and include it as X-API-Key:

export UKG_KEY="ukg_<prefix>_<secret>"
curl -H "X-API-Key: $UKG_KEY" http://localhost:5000/api/v1/gateway/chat ...

LLM Gateway Request

curl -X POST http://localhost:5000/api/v1/gateway/chat \
  -H "X-API-Key: $UKG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Summarize the compliance impact of this control change."
      }
    ],
    "model": "gpt-5.5",
    "tier": "2"
  }'

Tier 2+ responses include a verifiable audit footer:

[UKG Audit Trace]
Tier: 2
Active Axes: ...
Personas Invoked: ...
Confidence: 0.395
Refinement Steps Executed: ...
Compliance Flags: ...
Key Assumption to Verify: ...
What Changes if Wrong: ...

Every Tier 2+ run also writes a TruthAuditEvent row with a SHA-256 hash-chain receipt for EU AI Act Article 53 compliance.

Knowledge Graph Query

curl -H "X-API-Key: $UKG_KEY" \
  http://localhost:5000/api/v1/knowledge-nodes

Knowledge Algorithm Execution

curl -X POST http://localhost:5000/api/v1/ka/algorithms/KA-001/execute \
  -H "X-API-Key: $UKG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "claim": "New customer data must remain in-region.",
      "jurisdiction": "US"
    }
  }'

Standard Response Shape

{
  "success": true,
  "data": {},
  "error": null,
  "timestamp": "2026-01-11T19:35:00Z"
}

Deployment

Docker Compose

Use Docker Compose for local integration testing or single-host evaluation:

cp .env.template .env
docker compose up --build -d
docker compose ps

Cloud Container

Dockerfile.cloud builds the frontend and backend into a single runtime image:

docker build -f Dockerfile.cloud -t datalogicengine:latest .
docker run --env-file .env -p 5000:5000 -p 3000:3000 datalogicengine:latest

Production Checklist

  • Set FLASK_ENV=production.
  • Use PostgreSQL, Redis, Neo4j, and S3-compatible object storage outside the app container.
  • Set unique secrets for SECRET_KEY, JWT_SECRET_KEY, and SESSION_SECRET.
  • Configure exact CORS_ORIGINS.
  • Run database migrations instead of enabling AUTO_CREATE_SCHEMA.
  • Terminate TLS at a trusted reverse proxy or platform load balancer.
  • Enable Sentry or equivalent crash reporting.
  • Confirm /health, /ready, and /metrics are monitored.
  • Review docs/DEPLOYMENT.md, docs/OPERATIONAL_RUNBOOKS.md, and deploy/DEPLOYMENT_CHECKLIST.md.

Security and Compliance

DataLogicEngine includes security controls intended for enterprise deployments, but each deployment must still be threat-modeled and configured for its environment.

AreaBuilt-in Support
AuthenticationSession auth, JWT flows, MFA routes, SSO/OIDC integration hooks, desktop challenge flow.
AuthorizationRBAC utilities, admin route controls, tenant-aware patterns.
Request securityCSRF, request size limits, CORS enforcement, rate limiting, SSRF allowlisting utilities.
Data protectionSecret resolution controls, encryption manager, PII redaction utilities, audit logging.
AI governancePrompt-injection checks, provider usage tracking, trace IDs, policy/gateway hooks.
Supply chainGitHub Actions security workflow, Bandit, npm audit, pip-audit, SBOM-oriented workflow steps.
Release governanceWindows installer governance, signing workflows, integrity reporting, release checklist.

Security references:

🔒 Report Security Issues Privately:

Do not report vulnerabilities in public issues. Follow the private reporting process in SECURITY.md.

Observability

SignalLocation
LivenessGET /live
ReadinessGET /ready
Health summaryGET /health
Runtime metricsGET /metrics
API docsGET /api/docs
Gateway provider usageLLM gateway usage models and admin routes
Crash reportingSENTRY_DSN, SENTRY_TRACES_SAMPLE_RATE, SENTRY_PROFILES_SAMPLE_RATE
Run tracing/api/v1/trace/* and run-oriented UI routes

Recommended production integrations:

  • Prometheus-compatible scraping for /metrics.
  • Sentry or an equivalent error and performance backend.
  • Centralized JSON logs via python-json-logger and platform log shipping.
  • Alerting on readiness failures, provider error spikes, token cost anomalies, and authentication failures.

Testing

# Backend
python -m pytest tests/
python -m pytest tests/ --cov=backend --cov=models --cov-report=html --cov-report=term-missing --cov-report=json --cov-fail-under=70
python -m ruff check .
python -m pip_audit -r requirements.txt --desc

# Frontend
npm --prefix frontend ci
npm --prefix frontend run lint
npm --prefix frontend run typecheck
npm --prefix frontend run test
npm --prefix frontend audit --audit-level=high

Current CI Runs

  • ✅ Backend tests and dependency audit
  • ✅ Frontend lint, typecheck, tests, and build
  • ✅ Security scan workflow
  • ✅ Deploy build and test workflow
  • ✅ Windows packaging smoke test
  • ✅ Governance and release checklist workflows

Roadmap

HorizonFocus
Near termComplete app-readiness evidence: authenticated accessibility coverage, keyboard/NVDA checks, failure-mode tests, and export/delete end-to-end validation.
Near termTighten public API contracts, reduce legacy route aliases, and improve generated OpenAPI coverage.
Near termAdd public architecture assets under docs/assets/readme/.
Mid termExpand deployment reference material for Kubernetes, managed Postgres, managed Redis, and managed Neo4j.
Mid termPublish signed release artifacts with checksums and provenance metadata.
Long termHarden multi-tenant operations, cost controls, recursive persona evaluation, human feedback loops, and policy-as-code governance for larger deployments.

Getting Help

Documentation

Community & Support

  • Questions: Open a GitHub Discussion
  • Bug Reports: Create an issue with steps to reproduce
  • Security Issues: See SECURITY.md for responsible disclosure
  • API Documentation: Swagger UI at http://localhost:5000/api/docs (when running locally)

Contributing

Contributions are welcome when they align with the project license and governance model.

  1. Read CONTRIBUTING.md.
  2. Read CODE_OF_CONDUCT.md.
  3. Create an issue for non-trivial changes before implementation.
  4. Run backend and frontend checks locally.
  5. Submit a pull request using the repository template.

Development references:

License

DataLogicEngine is licensed under the PolyForm Noncommercial License 1.0.0.

Personal, research, and educational use are permitted under the license terms. Commercial use, production deployment in a business environment, or integration into a paid product requires a separate commercial license. See COMMERCIAL_LICENSE.md for details.

Repository Metadata

Existing Supporting Files

FileStatus
LICENSEPresent
COMMERCIAL_LICENSE.mdPresent
SECURITY.mdPresent
CONTRIBUTING.mdPresent
CODE_OF_CONDUCT.mdPresent
SUPPORT.mdPresent
CHANGELOG.mdPresent
.github/CODEOWNERSPresent
.github/pull_request_template.mdPresent
.github/ISSUE_TEMPLATE/*Present
.env.templatePresent
Dockerfile.cloud and docker-compose.ymlPresent

Recommended Additions

RecommendationPurpose
docs/assets/readme/architecture-overview.pngPublic README architecture image for GitHub social previews and non-Mermaid consumers.
.github/FUNDING.ymlOptional sponsorship metadata if the project accepts funding.
CITATION.cffCitation metadata for research and academic users.
GitHub repository topicsSuggested: ai, llm, knowledge-graph, flask, nextjs, governance, compliance, enterprise-ai.
Ver o original no GitHub

Bom para

Relacionados