AORM: AI-Augmented Orchestrator for Repository Management and Metrics

This repository houses the core implementation for the AI-Augmented Orchestrator for Repository Management (AORM). This system facilitates complex interactions between advanced generative models (OpenAI), code repository operations (Git), file system access, and time-series monitoring via Prometheus.

Structural Layout

AORM_ROOT/ ├── aorm_core/ # Essential AORM library packages ├── utilities/ # Auxiliary scripts and validation harness ├── monitoring_config/ # Prometheus instrumentation definitions ├── deployment.yml # Orchestration manifest (e.g., Docker Compose) ├── server_bootstrap.py # Primary server initialization script ├── run_aorm # Shortcut for executing interactive tests/tools └── README.md # Current documentation

Prerequisites

• Python environment, version 3.8 or newer is mandatory.
• Required libraries: FastAPI, Uvicorn, OpenAI SDK, GitPython, Requests.
• Docker and Docker Compose are necessary for activating the integrated Prometheus stack.

Setup Procedure

1. Clone the repository source code.
2. Install all necessary runtime dependencies:

bash pip install -r requirements.txt

Environment Configuration

Configuration relies on environment variables. Set these prior to execution:

For connections to Azure's OpenAI endpoints: bash export AZURE_OPENAI_ENDPOINT="your-azure-url" export AZURE_OPENAI_API_KEY="your-azure-secret" export AZURE_OPENAI_API_VERSION="2023-05-15" export AZURE_DEPLOYMENT_NAME="your-model-identifier"

For standard OpenAI connectivity: bash export OPENAI_API_KEY="your-openai-secret"

Optional overrides for model selection:

export OPENAI_CHAT_MODEL="gpt-4o-mini" # Default for conversational tasks export OPENAI_COMPLETION_MODEL="gpt-3.5-turbo-instruct" # Default for direct prompts

For metric scraping endpoint configuration: bash export PROMETHEUS_URL="http://localhost:9090" # Default scrape destination

Launching the Orchestrator Service

Initialize the AORM service using the dedicated startup script:

bash python utilities/start_server.py

Or invoke with specific runtime arguments:

bash python utilities/start_server.py --interface 0.0.0.0 --port 8000 --verbose

The operational endpoint will typically resolve to http://localhost:8000.

Unified Interactive Testing Harness

A provided executable script offers a centralized, user-friendly interface to validate all integrated capabilities:

bash ./run_aorm

This utility suite covers: - Local file system manipulation checks - Source control (Git) integration validation - In-memory state diagnostics - Performance monitoring (Prometheus) simulations and testing - Orchestrator service lifecycle management - Initial environment verification steps

Specific Component Validation

Individual testing modules are accessible directly:

Verify OpenAI integration layer connectivity: bash python utilities/test_ai_client.py

Test Git repository communication (specify the target URL): bash python utilities/test_git_interface.py https://github.com/organization/project_repo

Validate capability to analyze code differences (e.g., for dependency checks): bash python utilities/test_diff_analyzer.py https://github.com/organization/project_repo [specific_commit_hash]

Validate file I/O operations: bash python utilities/test_filesystem_ops.py

Execute tests simulating LangFlow interaction with AORM: bash python utilities/test_langflow_interface.py [OPTIONAL_REPO_URL]

Validate metric collection connectivity: bash python utilities/test_metrics_collector.py [prometheus_address]

Deep Git Code Analysis

For sophisticated, AI-driven repository review:

bash python utilities/langflow_repo_analyst.py https://github.com/organization/project_repo

Perform targeted content searches within the repository structure:

bash python utilities/langflow_repo_analyst.py https://github.com/organization/project_repo --seek "class Configuration"

Generate AI insights based on the most recent commit delta:

bash python utilities/langflow_repo_analyst.py https://github.com/organization/project_repo --delta

Memory Diagnostics and Stress Testing

AORM incorporates internal mechanisms for memory observation:

bash

Execute AI-assisted memory diagnostic reports

python utilities/diagnose_memory_ai.py

Launch interactive visualization dashboard for system memory

python utilities/visualize_memory_state.py

Initiate memory load alerting module

python utilities/trigger_memory_warnings.py

You can impose controlled memory load to test resilience:

bash python utilities/simulate_memory_stress.py --threshold 85 --duration 300

Prometheus Observability Framework

Deployment Steps

1. Instantiate the monitoring stack using the provided manifest:

bash docker compose up -d

This action deploys: - The Prometheus server (Queryable at http://localhost:9090) - Node Exporter (for host machine metrics) - cAdvisor (for container runtime telemetry)

1. To induce load for stress testing purposes, deploy the dedicated memory stress container:

bash docker compose up -d --build load_simulator

Alternatively, use the script utility: bash ./utilities/container_load_test.sh start

Docker Configuration Variants and State Reset

This project accommodates various deployment topologies through alternate configuration files and robust cleanup scripts:

Configuration Options

• Default Configuration (deployment.yml): Employs custom Dockerfiles for Prometheus and Langflow to guarantee consistent user permissions across environments.
• Network Bridge Variant (deployment.bridge.yml): An alternative setup utilizing standard bridge networking, beneficial in constrained host environments.

Custom Dockerfiles for Permission Guarantee

Custom build files resolve common Linux user permission conflicts:

• Dockerfile.prometheus_build: Configures the Prometheus environment, explicitly setting ownership permissions suitable for the non-privileged nobody user.
• Dockerfile.langflow_build: Ensures the Langflow container receives necessary components without altering file ownership, preventing access denial errors.

This methodology sidesteps the unreliability of host volume mounts which often create cross-system permission mismatches.

Service Reset Utilities

• Full Stack Reset (reset_all.sh): Reinitializes all dependent containers with a single command. bash # Basic reset (retains existing persistent volume data) ./reset_all.sh

# Complete reset (erases volumes before rebuilding) ./reset_all.sh --wipe

• Component-Specific Reset: bash # Reinitialize only the Prometheus component ./reset_prometheus.sh

# Reinitialize only the Langflow component ./reset_langflow.sh

These scripts guarantee containers possess correct privilege levels and reflect the latest source code changes.

Debugging Notes

If permission denials occur: 1. Re-execute the relevant reset script to force a fresh build. 2. Inspect service output: docker compose logs <service_name> 3. Confirm that any newly added LangFlow components are explicitly referenced in Dockerfile.langflow_build.

New Machine Deployment

For initial deployment on a fresh host: 1. Clone the repository. 2. Grant execution rights: chmod +x *.sh 3. Execute the primary reset script: ./reset_all.sh

The specialized Dockerfiles manage the necessary permission configurations autonomously.

Interacting via the Prometheus Client Library

The AORMClient class encapsulates Prometheus functionality:

python from langflow import AORMClient

Establish connection to the AORM service

mcp_client = AORMClient(service_url="http://localhost:8000")

Retrieve the current status metric

status_check = mcp_client.query_metric("up")

Execute a time-series query

volume_trend = mcp_client.query_time_series( query="increase(node_network_receive_bytes_total{device='eth0'}[5m])", start_time="2023-03-01T00:00:00Z", end_time="2023-03-01T01:00:00Z", interval="15s" )

Fetch metadata: all registered metric identifiers

metadata_labels = mcp_client.fetch_all_labels()

Fetch known values associated with a specific identifier

identifier_values = mcp_client.fetch_label_values("instance")

Review system components being monitored

targets_list = mcp_client.fetch_monitored_targets()

Get active alert notifications

active_alerts = mcp_client.fetch_current_alerts()

Essential PromQL Metrics

• CPU Utilization (Non-Idle): rate(node_cpu_seconds_total{mode!="idle"}[1m])
• Memory Consumed: node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes
• Filesystem Utilization: node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"}
• Container CPU Rate: rate(container_cpu_usage_seconds_total[1m])
• Container Memory Footprint: container_memory_usage_bytes

Service API Interface

Generative Model Endpoints (OpenAI)

• GET /api/v1/models - Catalog of accessible models
• GET /api/v1/models/{model_id} - Specific model metadata
• POST /api/v1/models/azure/completion - Generate text via Azure endpoint
• POST /api/v1/models/azure/chat - Engage conversationally via Azure endpoint
• POST /api/v1/models/standard/chat - Conversational interaction using standard OpenAI API
• POST /api/v1/models/standard/completion - Direct text generation via standard OpenAI API

Version Control Endpoints (Git)

• POST /api/v1/models/git/inspect - Comprehensive analysis of a specified Git repository
• POST /api/v1/models/git/seek - Pattern matching within repository files
• POST /api/v1/models/git/delta - Retrieve and analyze the most recent commit difference

Local Resource Endpoints (Filesystem)

• POST /api/v1/models/fs/enumerate - List directory entries
• POST /api/v1/models/fs/fetch - Retrieve content of a file
• POST /api/v1/models/fs/batch_fetch - Read content from multiple specified files
• POST /api/v1/models/fs/persist - Write new content to a designated file
• POST /api/v1/models/fs/revise - Apply sequential modifications to a file
• POST /api/v1/models/fs/mkdir - Create a new directory structure
• POST /api/v1/models/fs/relocate - Move or rename a file/directory
• POST /api/v1/models/fs/pattern_search - Locate files matching a wildcard expression
• POST /api/v1/models/fs/metadata - Obtain details (size, timestamps) of a file/directory

Monitoring Endpoints (Prometheus)

• POST /api/v1/models/metrics/query - Execute immediate (instant) metric retrieval
• POST /api/v1/models/metrics/range_query - Execute time-series metric retrieval
• POST /api/v1/models/metrics/series_data - Fetch raw series information
• GET /api/v1/models/metrics/labels - List all available metric identifiers
• POST /api/v1/models/metrics/label_values - Retrieve distinct values for a chosen identifier
• GET /api/v1/models/metrics/targets - List monitored endpoints
• GET /api/v1/models/metrics/rules - Retrieve configured alerting rules
• GET /api/v1/models/metrics/alerts - Report on active alerts

Client Interaction Examples (via AORMClient)

You can leverage the AORMClient within LangFlow graphs by providing the AORM service URL:

python from langflow import AORMClient

mcp_connector = AORMClient(service_url="http://localhost:8000")

Fetch supported model list

model_catalog = mcp_connector.get_models() print(model_catalog)

Engage standard chat model

chat_output = mcp_connector.chat_interaction( model_id="standard/chat", conversation_history=[ {"role": "system", "content": "Act as a helpful system administrator."}, {"role": "user", "content": "Explain container orchestration."} ], token_limit=100, creativity_temp=0.7 ) print(chat_output)

Request direct text completion

completion_output = mcp_connector.text_completion( model_id="standard/completion", input_prompt="Write a concise Python decorator for timing functions:", token_limit=150, creativity_temp=0.7 ) print(completion_output)

Initiate repository scan

repo_scan_results = mcp_connector.scan_git_repo("https://github.com/org/project") print(repo_scan_results)

Search for specific code blocks

search_results = mcp_connector.seek_in_git_repo("https://github.com/org/project", "init method") print(search_results)

Get status of latest changes

diff_summary = mcp_connector.get_latest_git_delta("https://github.com/org/project") print(diff_summary)

List files in the current operational directory

local_files = mcp_connector.list_directory_contents() print(local_files)

Access file data

file_data = mcp_connector.read_file_content("config/settings.ini") print(file_data)

Create a new file

write_status = mcp_connector.write_file_content("output/report.log", "Execution finished.") print(write_status)

Glob search for Python scripts

python_files_found = mcp_connector.search_filesystem("*.py") print(python_files_found)

Utilizing the CodeInspector Class

For structured Git code inspection workflows, employ the specialized CodeInspector:

python from langflow_repo_analyst import CodeInspector

Initialize the inspector linked to the AORM service

investigator = CodeInspector(service_url="http://localhost:8000")

Analyze the repository structure and content

investigator.inspect_repository("https://github.com/org/project")

Obtain a high-level summary of findings

overall_summary = investigator.retrieve_summary() print(overall_summary)

Request AI-driven improvement suggestions

improvement_suggestions = investigator.retrieve_ai_suggestions() print(improvement_suggestions)

Analyze occurrences of a specified code construct

construct_report = investigator.analyze_code_construct("async def") print(construct_report)

Retrieve the snapshot of the most recent commit's changes

last_delta = investigator.get_latest_commit_delta() print(last_delta)

Generate a human-readable synopsis of the commit delta

formatted_report = investigator.summarize_delta_report() print(formatted_report)

Request AI interpretation of the commit's impact

impact_assessment = investigator.assess_delta_with_ai() print(impact_assessment)

Common Issue Resolution

Prometheus Connectivity Problems

1. Confirm Prometheus service health: docker ps | grep prometheus
2. Verify UI accessibility: http://localhost:9090
3. Ensure the AORM backend service is active and reachable.
4. Review AORM server logs for connection failures or timeouts.
5. Test connectivity with the most basic query (e.g., up).

OpenAI Service Failures

1. Double-check that all required API credentials are correctly exported.
2. Investigate potential throttling or service quota exhaustion.
3. Confirm that the specified model identifiers are valid for your credentials.

Git Operation Errors

1. Ensure the remote repository URL is valid and publicly accessible (or credentials are provided for private repos).
2. Confirm that the GitPython dependency is functional.