RAGIX v0.62.0

(Retrieval-Augmented Generative Interactive eXecution Agent)

A Sovereign Development Platform for AI-Assisted Software Engineering

Version: 0.62.0 | Author: Olivier Vitrac, PhD, HDR | olivier.vitrac@adservio.fr | Adservio Updated: 2025-12-20 | Codebase: 500K+ LOC analyzed in production

Why RAGIX?

RAGIX is a sovereign development platform for building AI-assisted tools that transforms local LLMs into disciplined software engineering assistants. Unlike cloud-based AI coding tools, RAGIX provides:

Sovereignty by Design

100% local execution — No data leaves your infrastructure, air-gapped mode available
Model-agnostic — Works with Ollama (Mistral, Llama, Qwen, DeepSeek) or commercial APIs
Auditable operations — SHA256-verified command logs, complete provenance tracking

Production-Ready Architecture

Deterministic kernels — KOAS (Kernel-Orchestrated Audit System) ensures reproducible results
Hybrid reasoning — LLMs for planning, kernels for computation—no hallucinated metrics
MCP protocol — Standard tool exposure for Claude Code, custom agents, and multi-server collaboration

Enterprise Capabilities

Code audit & metrics — AST analysis, complexity hotspots, tech debt estimation, risk matrices
Security scanning — Network discovery, vulnerability assessment, compliance checking (ANSSI/NIST/CIS)
Multiple interfaces — Web UI, CLI, REST API, MCP server, WebSocket streaming

Development Platform

RAGIX is not just a tool—it's a platform for building sovereign AI systems:

Extensible tooling — Add custom MCP tools, reasoning engines, or domain-specific kernels
Collective intelligence — Multiple RAGIX instances can collaborate on complex tasks
Local-first research — Experiment with 200B+ parameter models on local hardware (GB10-ready)

Make local LLMs behave like disciplined software engineers. Reproducible, auditable, sovereign—without cloud dependencies.

ragix-demo-loop.mp4

▶️ Watch the full audit demo on YouTube: https://youtu.be/vDHI70ZPnDE

Quick Start

Option A: One-Click Launcher (Conda + Streamlit GUI)

git clone https://github.com/ovitrac/RAGIX.git
cd RAGIX
./launch_ragix.sh

This script automatically:

Initializes Conda and creates ragix-env environment
Installs all dependencies + RAGIX package
Checks Ollama status and available models
Presents an interactive menu (select option 7 for ragix-web)

Option B: Manual Setup (venv)

git clone https://github.com/ovitrac/RAGIX.git
cd RAGIX
python3 -m venv .venv && source .venv/bin/activate

# Install dependencies then RAGIX package (BOTH required!)
pip install -r requirements.txt
pip install -e .   # MUST run after requirements.txt (required to install ragix-web)

# Start the Web UI
ragix-web

Common Error: ModuleNotFoundError: No module named 'ragix_core' Solution: Run pip install -e . — this installs RAGIX itself, not just dependencies.

Option C: Conda Environment

git clone https://github.com/ovitrac/RAGIX.git
cd RAGIX
conda env create -f environment.yaml
conda activate ragix-env
pip install -e .

ragix-web

Web UI Access

ragix-web is the most advanced interface with full AI capabilities. It opens http://localhost:8080 and provides:

Dashboard — Project overview and metrics
Chat — AI-assisted coding with local LLMs
Reasoning — Multi-step workflow visualization
AST Analysis — Code structure and dependencies
Project RAG — Semantic search across your codebase
Audit — Risk matrix, drift tracking, compliance
Partitioner — Visual dependency graphs with propagation algorithms

Note: ragix-web creates configuration and cache files in $HOME/.ragix/ for session persistence.

Tip: For full AI capabilities, start Ollama: ollama serve && ollama pull mistral

Available Launchers

Launcher	Description
`./launch_ragix.sh`	Interactive menu with 7 options (Conda)
`./launch_ragix.sh gui`	Direct: Streamlit GUI (port 8501)
`./launch_ragix.sh web`	Direct: RAGIX-WEB FastAPI (port 8080)
`./launch_ragix.sh mcp`	Direct: MCP server
`source ragixinit.sh`	Set environment variables (model, sandbox, profile)

CLI Entry Points (after `pip install -e .`)

Command	Description
`ragix-web`	Most advanced UI — FastAPI (port 8080), creates `~/.ragix/`
`ragix`	Core CLI with subcommands
`ragix-unix-agent`	Interactive Unix-RAG agent
`ragix-ast`	AST analysis (scan, metrics, hotspots)
`ragix-koas`	KOAS kernel orchestrator
`ragix-index`	Project indexing for RAG
`ragix-batch`	Batch processing pipelines
`ragix-vault`	Encrypted credential vault
`ragix-wasp`	WASP security scanner

Without install: PYTHONPATH=. python ragix_web/server.py

Returning Users: Reactivate Your Environment

If you installed RAGIX before and want to use it again, you need to reactivate the environment first:

Install Method	Environment Name	Location	Reactivation Command
Option A (Conda launcher)	`ragix-env`	`~/anaconda3/envs/ragix-env/`	`conda activate ragix-env`
Option B (venv)	`.venv`	`./RAGIX/.venv/`	`cd RAGIX && source .venv/bin/activate`
Option C (Conda manual)	`ragix-env`	`~/anaconda3/envs/ragix-env/`	`conda activate ragix-env`

Quick reference:

# If you used venv (Option B) — must be in RAGIX folder
cd /path/to/RAGIX
source .venv/bin/activate
ragix-web

# If you used Conda (Option A or C) — works from anywhere
conda activate ragix-env
ragix-web

How to know if environment is active?

Your terminal prompt shows (.venv) or (ragix-env) at the beginning

Run which python — should point to the environment, not system Python

Platform Capabilities

🖥️ Four Access Modes

Interface	Use Case	Features
Web UI	Interactive development	7 specialized tabs, real-time streaming, visualizations
CLI	Automation & scripting	15+ commands, batch processing, CI/CD integration
MCP Server	Claude Desktop	Native integration, tool schemas, bidirectional
REST API	Custom integrations	FastAPI, WebSocket, OpenAPI docs

🔍 Dual RAG Architecture

RAG Type	Scope	Storage	Use Case
Unix-RAG	Shell-native	In-memory	Real-time code exploration with `grep`, `find`, `awk`
Project RAG	Per-project	ChromaDB	Semantic search, concept discovery, knowledge graphs

Both support hybrid search (BM25 + vector) with multiple fusion strategies: RRF, Weighted, Interleave, Rerank.

🌳 AST Analysis & Code Metrics

Professional-grade static analysis for Java and Python:

ragix-ast scan ./src --lang java          # Extract 18K+ symbols
ragix-ast metrics ./src                   # Complexity, debt, maintainability
ragix-ast hotspots ./src --top 20         # Find complexity hotspots
ragix-ast graph ./src --output deps.html  # Interactive dependency graph
ragix-ast matrix ./src --level package    # DSM with cycle detection

Production-tested: 1,315 Java files, 18,210 symbols, 45,113 dependencies, 362h tech debt estimated in ~10 seconds.

📊 Code Audit & Governance

Feature	Description
Risk Matrix	Visual risk assessment with configurable weights
Drift Tracking	Monitor code changes over time
Dead Code Detection	Find isolated classes (no callers AND no callees)
Service Detection	Enterprise patterns (SIAS, IOWIZME)
Compliance Reports	PDF/HTML audit reports

🧩 Codebase Partitioner

Visual tool for understanding and decomposing large codebases:

Graph Propagation Algorithm — Multi-phase directional classification
Dependency Visualization — Force-directed graphs with D3.js
MDS Layout — Eigendecomposition for optimal positioning
Export — JSON, CSV, SVG, PNG for documentation

🤖 Multi-Agent Workflows

Pre-built templates for common tasks:

Template	Steps	Use Case
`bug_fix`	Locate → Diagnose → Fix → Test	Bug resolution
`feature_addition`	Design → Implement → Test → Document	New features
`code_review`	Quality + Security review	PR review
`refactoring`	Analyze → Plan → Refactor → Verify	Tech debt
`security_audit`	Static analysis + Dependency checks	Security

🔒 Safety & Sovereignty

Feature	Description
Three Profiles	`safe-read-only`, `dev`, `unsafe`
Dangerous Pattern Filtering	Blocks `rm -rf`, `dd`, `mkfs`, etc.
Git Protection	Prevents destructive operations
Audit Trail	SHA256 hash chain for all operations
Air-Gapped Mode	Enforces local-only processing

The RAGIX Ecosystem

RAGIX is part of a suite of sovereign AI tools:

🔐 CloakMCP — Secret Sanitization

Deterministic sanitizer for secrets before LLM exposure.

Reversible redaction with encrypted vaults
Policy-driven detection (regex, entropy, JWT, SSH keys)
VS Code integration and CLI tools
Repository: github.com/ovitrac/CloakMCP

📚 RAGGAE — Enterprise Document RAG

Production-ready RAG for document processing (tenders, CVs, reports).

Hybrid retrieval (FAISS + BM25)
NLI compliance checking via Ollama
Multi-format (PDF, DOCX, ODT, Markdown)
Full traceability (document → page → block → bounding box)
Repository: github.com/ovitrac/RAGGAE
Website: raggae.pages.dev

Documentation

📖 Documentation Index

docs/INDEX.md — Complete documentation navigation hub with reading guides by topic and goal.

📖 DeepWiki (AI-Generated)

deepwiki.com/ovitrac/RAGIX — AI-generated documentation covering:

Six-tier architecture (Presentation → Storage)
Agent orchestration and reasoning graphs
LLM integration patterns
RAG system internals
Security model

Note: DeepWiki is generated by Devin and refreshes every ~5 days. This repository is typically ahead with latest features.

📁 Core Documentation

Document	Description
docs/INDEX.md	Documentation navigation hub
docs/MCP.md	Model Context Protocol in RAGIX
docs/REASONING.md	Reasoning engines (ContractiveReasoner, v30)
docs/KOAS.md	Kernel-Orchestrated Audit System
docs/ARCHITECTURE.md	System architecture

📁 Guides & References

Document	Description
QUICKSTART_CLAUDE_CODE.md	Getting started guide
docs/API_REFERENCE.md	REST API documentation
docs/CLI_GUIDE.md	Command-line interface
docs/AST_GUIDE.md	AST analysis guide
docs/KOAS_MCP_REFERENCE.md	KOAS MCP tool reference
CHANGELOG.md	Version history

Architecture

flowchart TB
    subgraph "User Interfaces"
        WEB["🌐 Web UI (ragix-web)"]
        CLI["🖥️ CLI Tools"]
        MCP["🔌 MCP Server"]
        API["📡 REST API"]
    end

    subgraph "Orchestration"
        ORCH["🧠 Graph Executor"]
        REASON["🔄 Reasoning Loop"]
        TEMPLATES["📋 Workflow Templates"]
    end

    subgraph "Analysis & Audit"
        AST["🌳 AST Parser"]
        METRICS["📈 Code Metrics"]
        AUDIT["📊 Risk Matrix"]
        PARTITION["🧩 Partitioner"]
    end

    subgraph "Retrieval"
        UNIX_RAG["🔧 Unix-RAG"]
        PROJ_RAG["📚 Project RAG"]
        HYBRID["🔍 Hybrid Search"]
    end

    subgraph "Execution"
        SHELL["🐚 Sandboxed Shell"]
        LLM["🤖 LLM Backends"]
        SAFETY["🔒 Safety Policies"]
    end

    WEB --> ORCH
    CLI --> ORCH
    MCP --> ORCH
    API --> ORCH

    ORCH --> REASON
    ORCH --> TEMPLATES

    REASON --> AST
    REASON --> UNIX_RAG
    REASON --> PROJ_RAG

    AST --> METRICS
    AST --> AUDIT
    AST --> PARTITION

    UNIX_RAG --> SHELL
    PROJ_RAG --> HYBRID

    SHELL --> SAFETY
    REASON --> LLM
    LLM --> SAFETY

Installation

Option A: Quick Install

git clone https://github.com/ovitrac/RAGIX.git
cd RAGIX
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Option B: With Ollama (Recommended)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull mistral        # Fast, general purpose
ollama pull qwen2.5:14b    # Better reasoning
ollama pull deepseek-coder # Code-specialized

# Start RAGIX
python ragix_web/server.py

Option C: Using Launcher

./start_ragix.sh          # Interactive launcher
./start_ragix.sh --web    # Direct web server start
./start_ragix.sh --cli    # CLI mode

LLM Backend Configuration

RAGIX supports multiple LLM backends with a sovereignty-first model:

Backend	Type	Configuration
Ollama	Local	Default, no API key needed
Claude	Cloud	`ANTHROPIC_API_KEY` env var
OpenAI	Cloud	`OPENAI_API_KEY` env var

Configure in ragix.yaml or via Web UI Settings:

llm:
  backend: ollama
  model: mistral
  temperature: 0.7

sovereignty:
  enforce_local: true  # Block cloud backends

API Reference

REST Endpoints

Endpoint	Method	Description
`/api/health`	GET	Health check
`/api/sessions`	POST	Create session
`/api/threads/{id}/messages`	POST	Send message
`/api/ast/scan`	POST	Scan codebase
`/api/ast/metrics`	GET	Get metrics
`/api/ast/partition`	POST	Run partitioner
`/api/rag/search`	POST	Search documents
`/api/rag/index`	POST	Index files

WebSocket

const ws = new WebSocket('ws://localhost:8421/ws/chat');
ws.send(JSON.stringify({ message: "Analyze this code", session_id: "..." }));

Full API documentation: docs/API_REFERENCE.md

Tools & Applications

🚀 Main Applications

Application	Entry Point	Description
Web UI	`python ragix_web/server.py`	Full-featured dashboard (8 tabs)
Unix-RAG Agent	`python unix-rag-agent.py`	Interactive shell-based assistant
MCP Server	`python MCP/ragix_mcp_server.py`	Claude Desktop integration
Radial Server	`python ragix_unix/radial_server.py`	Live dependency explorer

🛠️ CLI Tools

Tool	Command	Description
AST Analysis	`ragix-ast scan/metrics/graph/matrix/radial`	Code analysis & visualization
Project Index	`ragix-unix index_cli.py`	Index codebase for RAG
Batch Processing	`ragix-unix batch_cli.py`	Bulk file operations
Vault Manager	`ragix-unix vault_cli.py`	Secure credential storage
WASP Tools	`ragix-unix wasp_cli.py`	Workflow automation
Core CLI	`ragix_core/cli.py`	Main orchestrator CLI

📡 API Routers (REST + WebSocket)

Router	Endpoints	Purpose
`sessions.py`	`/api/sessions/*`	Session management
`threads.py`	`/api/threads/*`	Conversation threads
`reasoning.py`	`/api/reasoning/*`	Multi-step workflows
`rag.py`	`/api/rag/*`	Document RAG
`rag_project.py`	`/api/rag/project/*`	Project-level RAG
`audit.py`	`/api/audit/*`	Code audit & partitioner
`agents.py`	`/api/agents/*`	Agent configuration
`memory.py`	`/api/memory/*`	Episodic memory
`context.py`	`/api/context/*`	Global context
`logs.py`	`/api/logs/*`	Operation logs

🔧 Shell Scripts

Script	Purpose
`launch_ragix.sh`	Interactive launcher with menu
`ragixinit.sh`	Environment initialization
`release.sh`	Release automation
`rt.sh`, `rt-find.sh`, `rt-grep.sh`	Testing utilities

🧪 Test Suites

Test File	Coverage
`test_ast.py`	AST parsing & metrics
`test_reasoning_graph.py`	Multi-step reasoning
`test_graph_executor.py`	Workflow execution
`test_hybrid_search.py`	BM25 + Vector search
`test_bm25_index.py`	Keyword indexing
`test_workflow_templates.py`	Pre-built workflows
`test_wasp_*.py`	WASP integration
`tests/audit/*`	Audit & partitioner

📚 Examples

Example	Description
`claude_demo.py`	Claude API integration
`hybrid_search_example.py`	Hybrid RAG demo
`resilience_example.py`	Retry & circuit breaker
`workflow_example.py`	Multi-agent workflow
`test_llm_backends.sh`	Backend comparison

🔒 Security Examples (`examples/security/`)

Example	Description
`local_network/`	Network discovery & port scanning
`web_audit/`	Web application security audit
`compliance_check/`	ANSSI/NIST/CIS compliance
`config_audit/`	Firewall configuration analysis
`run_security_demo.sh`	Interactive security demo

📊 Audit Examples (`examples/audit/`)

Example	Description
`volumetry_analysis/`	Risk weighted by traffic (IOWIZME 4M msg/day)
`microservices/`	Service catalog & dependency analysis
`java_monolith/`	Complexity hotspots & refactoring
`full_audit/`	Comprehensive system audit
`run_audit_demo.sh`	Interactive audit demo

Full CLI reference: docs/CLI_GUIDE.md

Project Structure

RAGIX/
├── ragix_core/          # Core libraries
│   ├── agents/          # Agent implementations
│   ├── reasoning_slim/  # Reasoning engine
│   ├── ast_*.py         # AST analysis
│   └── rag_*.py         # RAG components
├── ragix_web/           # Web application
│   ├── server.py        # FastAPI server
│   ├── routers/         # API routes
│   └── static/          # Frontend
├── ragix_unix/          # Unix tools
│   ├── unix_rag_agent.py
│   └── radial_server.py
├── ragix_audit/         # Audit tools
│   └── partitioner.py
├── MCP/                 # MCP integration
├── docs/                # Documentation
├── tests/               # Test suite
└── examples/            # Usage examples

Testing

# Run all tests
pytest tests/ -v

# Run specific test suite
pytest tests/audit/ -v
pytest tests/ast/ -v

# With coverage
pytest tests/ --cov=ragix_core --cov-report=html

What's New

See CHANGELOG.md for complete version history.

Latest: v0.62.0 (2025-12-20)

KOAS MCP Consolidation: 38 MCP tools total, 16 KOAS-specific tools optimized for LLM consumption
Interactive Demo UI: FastAPI + WebSocket demo with model selection, tool trace, chat interface
Academic Documentation: Comprehensive MCP.md and REASONING.md with protocol-first perspective
Markdown Chat: Proper markdown rendering in demo UI with history sidebar
Documentation Index: docs/INDEX.md linking all documentation with reading guides

Recent highlights:

v0.61.0: KOAS Security Kernels (10 kernels), ANSSI/NIST/CIS compliance frameworks
v0.60.0: KOAS Volumetry Kernels for traffic-weighted risk assessment
v0.58.0: Partitioner UI polish with search filter and accordion pagination

Roadmap

Priority	Feature	Status
✅	Multi-agent workflows	Complete
✅	Hybrid RAG (BM25 + Vector)	Complete
✅	AST analysis (Java/Python)	Complete
✅	Code audit & partitioning	Complete
✅	MCP integration	Complete
🔄	Enhanced reasoning traces	In progress
📋	Multi-language AST (Go, Rust)	Planned
📋	Distributed agent execution	Planned

License

MIT License — See LICENSE for details.

Author

Olivier Vitrac, PhD, HDR Head of Innovation Lab, Adservio olivier.vitrac@adservio.fr

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Follow existing code style and documentation standards
Add tests for new functionality
Submit a pull request

Acknowledgments

Ollama — Local LLM serving
FastAPI — Web framework
D3.js — Visualizations
ChromaDB — Vector storage
javalang — Java AST parsing

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
MCP		MCP
assets		assets
benchmark_logs/results		benchmark_logs/results
demos		demos
docs		docs
examples		examples
plugins		plugins
ragix_audit		ragix_audit
ragix_core		ragix_core
ragix_kernels		ragix_kernels
ragix_unix		ragix_unix
ragix_web		ragix_web
scripts		scripts
templates		templates
tests		tests
wasp_tools		wasp_tools
.claude_context.md		.claude_context.md
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
NOTES-v0.56.0.md		NOTES-v0.56.0.md
NOTES-v0.57.0.md		NOTES-v0.57.0.md
NOTES-v0.58.0.md		NOTES-v0.58.0.md
NOTES-v0.60.0.md		NOTES-v0.60.0.md
README.md		README.md
RELEASE.md		RELEASE.md
ROADMAP.md		ROADMAP.md
TODO.md		TODO.md
complexity_explanation.txt		complexity_explanation.txt
environment.yaml		environment.yaml
file_list.txt		file_list.txt
graphql_usage.txt		graphql_usage.txt
launch_ragix.sh		launch_ragix.sh
md_files_list.txt		md_files_list.txt
pyproject.toml		pyproject.toml
python_files_list.txt		python_files_list.txt
ragix.yaml		ragix.yaml
ragix_app.py		ragix_app.py
ragix_tools.py		ragix_tools.py
ragixinit.sh		ragixinit.sh
release.sh		release.sh
requirements.txt		requirements.txt
rest_usage.txt		rest_usage.txt
rest_vs_graphql.txt		rest_vs_graphql.txt
rt-find.sh		rt-find.sh
rt-grep.sh		rt-grep.sh
rt.sh		rt.sh
temp_files.txt		temp_files.txt
test_swe_tools.sh		test_swe_tools.sh
unix-rag-agent-new.py		unix-rag-agent-new.py
unix-rag-agent.py		unix-rag-agent.py

License

ovitrac/RAGIX

Folders and files

Latest commit

History

Repository files navigation

RAGIX v0.62.0

Why RAGIX?

Sovereignty by Design

Production-Ready Architecture

Enterprise Capabilities

Development Platform

Quick Start

Option A: One-Click Launcher (Conda + Streamlit GUI)

Option B: Manual Setup (venv)

Option C: Conda Environment

Web UI Access

Available Launchers

CLI Entry Points (after pip install -e .)

Returning Users: Reactivate Your Environment

Platform Capabilities

🖥️ Four Access Modes

🔍 Dual RAG Architecture

🌳 AST Analysis & Code Metrics

📊 Code Audit & Governance

🧩 Codebase Partitioner

🤖 Multi-Agent Workflows

🔒 Safety & Sovereignty

The RAGIX Ecosystem

🔐 CloakMCP — Secret Sanitization

📚 RAGGAE — Enterprise Document RAG

Documentation

📖 Documentation Index

📖 DeepWiki (AI-Generated)

📁 Core Documentation

📁 Guides & References

Architecture

Installation

Option A: Quick Install

Option B: With Ollama (Recommended)

Option C: Using Launcher

LLM Backend Configuration

API Reference

REST Endpoints

WebSocket

Tools & Applications

🚀 Main Applications

🛠️ CLI Tools

📡 API Routers (REST + WebSocket)

🔧 Shell Scripts

🧪 Test Suites

📚 Examples

🔒 Security Examples (examples/security/)

📊 Audit Examples (examples/audit/)

Project Structure

Testing

What's New

Roadmap

License

Author

Contributing

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Contributors 2

Languages

CLI Entry Points (after `pip install -e .`)

🔒 Security Examples (`examples/security/`)

📊 Audit Examples (`examples/audit/`)

Packages