Developer & Contributor Guide

Relevant source files

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

• AGENTS.md
• README.md
• configs/agents/agents_config.json
• monGARS_structure.txt
• scripts/manage_agents.py
• tests/AGENTS.md
• scripts/update_docs_metadata.py
• CURATION_GUIDE.md

This guide provides a comprehensive overview for developers and contributors to the monGARS project. It covers the project structure, development setup, contribution workflows, and key tooling. The monGARS project is a privacy-first AI assistant designed for resilient deployment, combining a FastAPI service, an adaptive cognition pipeline, a Django operator console, and optional ML training modules.

The contribution process is governed by a system of AGENTS.md files, which act as charters defining rules and guardrails for different parts of the repository. These are auto-generated and centrally managed, ensuring consistency and alignment with the project's roadmap.

Sources: README.md:5-9, AGENTS.md:3-8

Project Structure

The monGARS repository is organized into several key directories, each with a specific purpose. Understanding this structure is crucial for navigating the codebase and making contributions.

Sources: monGARS_structure.txt

This diagram shows the high-level directory structure of the monGARS project.

Sources: monGARS_structure.txt

Directory	Description
monGARS/	The core FastAPI application, including the API surface (api/) and cognition engine (core/).
modules/	Optional subsystems, such as the evolution engine and neuron trainers, with heavy dependencies gated behind runtime checks.
webapp/	The Django-based operator console for interacting with the FastAPI backend.
configs/	Centralized configuration files, including the master agents_config.json for managing AGENTS.md files.
scripts/	Automation and utility scripts for development, deployment, and maintenance.
tests/	The test suite, covering unit, integration, and long-haul validation tests.
docs/	Project documentation, including runbooks, architectural diagrams, and API references.
sdks/	Client SDKs for interacting with the monGARS API (Python and TypeScript).

Sources: monGARS_structure.txt, README.md:80-87, modules/AGENTS.md:5-7

Getting Started: Local Development

To set up a local development environment, you need Python 3.11+ and optionally Docker.

Sources: README.md:91-92

Setup Flow

The following diagram illustrates the steps for setting up and running the backend service locally.

Local Setup Commands

1. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # update secrets + URLs in .env
   

4. Initialize the database:

   python init_db.py
   

5. Run the FastAPI server:

   uvicorn monGARS.api.web_api:app --host 0.0.0.0 --port 8000 --reload
   

Sources: README.md:97-101

For container-based workflows, an interactive script is provided:

python scripts/docker_menu.py

This script manages the Docker Compose stack, including building images, starting/stopping services, and running diagnostics.

Sources: README.md:104-105

Contribution Workflow and Guardrails

All contributions must adhere to the guidelines defined in the AGENTS.md files. The root AGENTS.md establishes non-negotiable guardrails for all repository changes.

Sources: AGENTS.md:5-8

Core Principles

• Target Platforms: Backend tooling targets Python 3.11, and frontend assets use Node.js 18+.
• Code Formatting: Python code must be formatted with black and isort. TypeScript/JavaScript assets are linted with npm run lint.
• Testing: pytest must be run for backend changes, and npm run test for frontend changes.
• Documentation: Architectural and workflow changes must be documented in docs/ or the README.md.
• Configuration: All configuration should be loaded via monGARS.config.get_settings() to ensure consistency.
• Security: Secrets must be redacted in logs, and Dockerfiles/Kubernetes manifests kept aligned.

Sources: AGENTS.md:55-68

Contribution Flow

This diagram outlines the standard workflow for preparing a contribution.

Sources: AGENTS.md:56-59, tests/AGENTS.md:52-55

The AGENTS.md System

The repository uses a network of AGENTS.md files to define and enforce contribution rules at different scopes. These files are not meant to be edited manually. Instead, they are generated and managed by the scripts/manage_agents.py script, which uses configs/agents/agents_config.json as its source of truth.

Sources: AGENTS.md:3, configs/agents/agents_config.json

Managing AGENTS.md Files

The manage_agents.py script provides two main commands: refresh and create.

This diagram shows how manage_agents.py uses the central JSON config and the project roadmap to generate scoped AGENTS.md files.

Sources: scripts/manage_agents.py:202-214, 239-248

• refresh: Regenerates existing AGENTS.md files from the central configuration. This should be run after editing configs/agents/agents_config.json.

  python scripts/manage_agents.py refresh
  

• create: Scaffolds a new AGENTS.md file for a new subsystem or directory and adds its profile to agents_config.json.

  python scripts/manage_agents.py create <directory> --title "New Subsystem Charter" --scope "Rules for the new subsystem."
  

Sources: AGENTS.md:12-14, scripts/manage_agents.py:284-311

Scoped Charters

Each AGENTS.md file defines a charter for a specific part of the codebase. Nested files add stricter rules.

File Path	Title	Scope
AGENTS.md	monGARS Delivery Charter	Applies to every repository change.
monGARS/AGENTS.md	monGARS Package Contract	Covers the primary FastAPI app, cognition services, and persistence layer.
monGARS/api/AGENTS.md	FastAPI Surface Standards	Applies to routers, schemas, and auth utilities.
modules/AGENTS.md	Optional Modules Charter	Covers optional subsystems under modules/.
tests/AGENTS.md	Test Suite Expectations	Applies to everything in tests/.

Sources: configs/agents/agents_config.json:8-25, 80-84, 114-117, 184-187, 298-301

Testing

The test suite is a critical component of the development process, ensuring stability and correctness. The expectations for tests are defined in tests/AGENTS.md.

Sources: tests/AGENTS.md

Key Conventions

• Asynchronous Tests: Use the pytest.mark.asyncio decorator.
• State Management: Fixtures in conftest.py should be used to reset shared state (e.g., caches) to ensure tests are hermetic.
• Dependencies: Heavy dependencies like Torch, spaCy, and external HTTP clients should be stubbed with fakes or patches.

Sources: tests/AGENTS.md:37-42

Running Tests

• Default command: Run all tests from the repository root.

  pytest
  

  (Currently 631 tests, ~110 seconds)
• Focused runs: Use -k <pattern> to run specific tests.
• Triage: Use --maxfail=1 to stop after the first failure.
• Coverage:

  pytest --cov=monGARS --cov=modules
  

• Frontend tests:

  npm run test
  

Sources: tests/AGENTS.md:52-55, AGENTS.md:58

Documentation

Documentation is a key part of the contribution process.

Updating Timestamps

All Markdown files (except AGENTS.md) contain a Last updated banner. This is managed automatically by a script that uses Git history to determine the date. Before creating a pull request, run this script to refresh the timestamps.

python scripts/update_docs_metadata.py

Sources: scripts/update_docs_metadata.py:5-11, 171-174, README.md:281-282

Curation Guide

For developers working with the ML datasets, the CURATION_GUIDE.md provides instructions on how to triage, validate, and curate datasets generated by the monGARS Deep Scanner. This includes reviewing QA reports, validating provenance, and promoting high-quality records for training.

Sources: CURATION_GUIDE.md

Summary

Contributing to monGARS involves adhering to a structured workflow centered around code quality, testing, and documentation. The AGENTS.md system provides clear, auto-managed guardrails for every part of the repository, ensuring that all contributions align with the project's standards and roadmap. By following the setup instructions and contribution flows outlined in this guide, developers can effectively participate in the evolution of the monGARS platform.