Welcome to monGARS

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• ROADMAP.md
• monGARS_structure.txt
• configs/agents/agents_config.json
• AGENTS.md
• sdks/python/README.md
• sdks/typescript/README.md
• scripts/manage_agents.py
• datasets/monGARS_llm/README.md

monGARS (Modular Neural Guardian for Autonomous Research & Support) is a privacy-first, modular AI assistant designed for resilient deployment across various environments, including workstations, edge appliances, and research clusters. The project provides an end-to-end ecosystem for experimentation, combining a FastAPI service for the core API, an adaptive cognition pipeline, a Django-based operator console, and optional modules for machine learning and model training.

The system is engineered for hardware-aware operations, with support for devices like Raspberry Pi and Jetson, and includes deployment configurations for Docker and Kubernetes. Its key capabilities include a conversational engine with memory-backed context, an "evolution engine" for retraining model adapters, and a self-improvement loop that refines its personality and performance over time.

Sources: README.md:7-12, 30-34

Architecture at a Glance

The monGARS system is built on a modular architecture that separates concerns into distinct, interoperable components. This design allows for graceful degradation when optional dependencies are unavailable and facilitates focused development on specific parts of the system.

Sources: README.md:43-45, monGARS_structure.txt

The following diagram illustrates the high-level interaction between the primary services.

Service Breakdown

The repository is organized into several key directories, each housing a core part of the system.

Component	Location	Responsibilities
FastAPI service	monGARS/api	Authentication, REST/WebSocket endpoints, dependency wiring
Cognition core	monGARS/core	Memory, reasoning, LLM integration, adaptive response generation
Evolution modules	modules/	Adapter training, diagnostics, research tooling
Django UI	webapp/	Operator-facing chat console and auth proxy
Persistence	init_db.py, monGARS/core/persistence.py	SQLModel schemas, Hippocampus caching, Redis/disk tiers
Tooling	scripts/, k8s/	Automation, orchestration, deployment manifests

Sources: README.md:104-113, monGARS_structure.txt

Key Features

monGARS integrates several advanced features to create a comprehensive AI assistant platform.

• Conversational Engine: Provides memory-backed context, curiosity-driven research capabilities, and adapts its conversational style.
• Memory Architecture: A hybrid approach blending in-memory (Hippocampus), SQL persistence, and Redis/disk caching layers.
• Evolution Engine: An automated system to retrain model adapters, roll out artifacts, and trigger optimizations during idle periods.
• Self-Improvement Loop: Persists personality profiles via SQLModel and refreshes them using LoRA-style adapters. It uses a SelfTrainingEngine to feed an MNTPTrainer for creating curated training batches.
• Web Interface: A Django-powered operator console with async views that proxies requests to the FastAPI backend.
• Hardware-Aware Operations: Includes worker tuning for low-power devices (Raspberry Pi/Jetson) and multi-architecture container builds.
• RAG Enrichment: Augments conversational flows with repository-aware context when rag_enabled is set.

Sources: README.md:24-34, modules/AGENTS.md:16-20

Conversational Pipeline

The conversational flow processes user input through multiple enrichment and adaptation stages before generating a response.

This diagram shows the sequence of events in the conversational pipeline.

Getting Started

You can run the monGARS stack locally using either direct Python execution or Docker Compose for a containerized environment.

Local Development

1. Setup Environment: Create and activate a Python 3.11+ virtual environment.
2. Install Dependencies: Run pip install -r requirements.txt.
3. Configure: Copy .env.example to .env and update secrets and URLs.
4. Initialize Database: Execute python init_db.py to apply migrations.
5. Run Server: Start the FastAPI app with uvicorn monGARS.api.web_api:app --reload.

Sources: README.md:121-127

Docker Compose

The project includes an interactive script to manage the Docker Compose stack, which simplifies setup and management.

python scripts/docker_menu.py

This script provides a menu to build, start, stop, and inspect services. It also handles initial configuration, such as creating the .env file, rotating default secrets, and managing optional profiles for services like Ollama and Ray.

Sources: README.md:129-132, 135-156

Project Roadmap

The project's development is structured into distinct phases, with most foundational, performance, and API work already completed. Future work is focused on sustainability and longevity.

This Gantt chart visualizes the completed and future phases of the project.

Development & Contribution

The project follows a set of defined guidelines to ensure code quality, consistency, and alignment with the roadmap.

Workflow Guardrails

• Technology Stack: Backend tooling uses Python 3.11, and frontend builds use Node.js 18+.
• Code Formatting: Python code is formatted with black and isort. TypeScript/JavaScript is linted with npm run lint.
• Testing: pytest is used for the backend (631 tests), and npm run test for frontend assets.
• Documentation: Architectural and workflow changes must be documented in the docs/ directory or README.md.
• Agent-Driven Development: AGENTS.md files, which define contribution rules for different modules, are auto-generated from configs/agents/agents_config.json using the scripts/manage_agents.py script.

Sources: AGENTS.md:51-62, scripts/manage_agents.py:7, configs/agents/agents_config.json:10-15

SDKs

To facilitate integration, monGARS provides SDKs for both Python and TypeScript.

• Python SDK: A client library built on httpx that offers both synchronous and asynchronous clients for interacting with the FastAPI service.
  Sources: sdks/python/README.md:3-7
• TypeScript SDK: A Promise-based wrapper for the REST API that runs in both Node.js and browser environments, using cross-fetch.
  Sources: sdks/typescript/README.md:3-6

LLM Alignment Dataset

The project maintains a specialized dataset for fine-tuning Large Language Models (LLMs) to understand the monGARS platform. This dataset is generated by scripts/generate_monGARS_llm_dataset.py and includes instruction/response pairs about the system's architecture, API, and operational runbooks. The dataset is split into training and validation sets and is integrated into the Docker Compose deployment for use by the self-training pipeline.

Sources: datasets/monGARS_llm/README.md:3-6, 17-23, scripts/generate_monGARS_llm_dataset.py

Conclusion

monGARS is a comprehensive and actively developed AI assistant platform with a strong emphasis on modularity, resilience, and self-improvement. Its architecture is designed for both ease of local development and robust deployment in various environments. The project's clear roadmap, extensive documentation, and structured contribution guidelines make it an accessible platform for developers and researchers interested in building and experimenting with advanced AI systems.

Sources: README.md:7-12, ROADMAP.md:3-5