adaptive-memory-multi-model-router 2.14.49 → 2.14.52

package/ARCHITECTURE.md

@@ -0,0 +1,346 @@
+# Architecture
+
+## A3M Router — Adaptive Memory Multi-Model Router
+
+A multi-provider LLM routing and orchestration engine. Routes prompts across 47+ providers, executes them in parallel with ensemble voting, and adapts model selection based on learned quality profiles, cost constraints, and task complexity.
+
+## High-Level Overview
+
+The system has three layers:
+
+```
+User / API / CLI / TUI
+        |
+  [Proxy Server / LangChain Adapter]
+        |
+   [Routing Engine]  ←── [Memory System]  ←── [Semantic Cache]
+        |
+   [Provider Layer]  ←── [Retry Handler]  ←── [Guardrails]
+        |
+   [47+ LLM APIs]
+```
+
+- **TypeScript Core** — routing, provider config, cost tracking, observability, cache, guardrails, proxy server, TUI
+- **Python Layer** — Universal Model Router (learned routing), HALO orchestration (hierarchical planning), MCTS workflow search
+- **Integrations** — LangChain adapter, MCP server, OpenAI-compatible proxy, CLI/TUI
+
+## Directory Structure
+
+```
+src/
+  index.ts                 # Main entry point — exports all public APIs, createA3MRouter()
+  sdk.ts                   # A3MRouter SDK class — route(), routeBatch(), recommend(), serve(), analyze()
+  routing/
+    providerRetry.ts       # Per-provider retry with exponential backoff + jitter, context window validation
+    providerHealth.ts      # Provider health monitoring
+    universal_router.py    # UniversalModelRouter — learned routing with online adaptation (Python)
+  providers/
+    providerConfig.ts      # 47+ provider definitions, config loading, health checks, runtime registration
+    registry.py            # Python provider registry with health monitoring
+    base.py                # Python base provider classes
+    anthropic.py           # Anthropic provider implementation (Python)
+    cerebras.py            # Cerebras provider implementation (Python)
+  memory/
+    memoryTree.ts          # MemoryTree — hierarchical chunk storage with search
+    autoFetch.ts           # Automatic memory fetching
+    obsidianVault.ts       # Obsidian vault integration
+    agentic_memory.py      # Agentic memory (Python)
+    semantic_memory.py     # Semantic memory (Python)
+    simple_memory.py       # Simple memory (Python)
+    working_memory.py      # Working memory (Python)
+  cost/
+    costTracker.ts         # Per-request cost tracking
+    budgetEnforcer.ts      # Budget limits, spend records, alerts
+  analytics/
+    costAnalytics.ts       # Advanced cost analytics, savings reports, projections
+  cache/
+    semanticCache.ts       # Embedding-based semantic cache with cosine similarity
+    research/              # Cache research files
+  security/
+    guardrails.ts          # Prompt injection, PII detection, content filtering, output validation
+  observability/
+    index.ts               # Observable exports
+    types.ts               # Span, Metric, RouteTrace types
+    tracer.ts              # Distributed tracing
+    metrics.ts             # Metrics collector
+    middleware.ts          # Express-style observability middleware
+  server/
+    proxyServer.ts         # OpenAI-compatible HTTP proxy — POST /v1/chat/completions, GET /v1/models
+    modelMapper.ts         # Model name resolution
+    dashboard.ts           # Server dashboard
+  integrations/
+    langchainAdapter.ts    # Drop-in ChatOpenAI replacement for LangChain
+    oauth.ts               # OAuth integration
+  cli/
+    setupWizard.ts         # Interactive setup wizard
+  tui/
+    index.ts               # TUI launch wrapper
+    dashboard.ts           # Blessed-based terminal dashboard
+  orchestration/           # (Python) HALO hierarchical orchestration
+    halo_orchestrator.py   # HALO orchestrator — 3-tier planning
+    task_planner.py        # Task decomposition into subtasks
+    role_assigner.py       # Agent role assignment
+    execution_engine.py    # Parallel execution with verification
+    mcts_workflow.py       # MCTS-based workflow search
+  workflows/               # (Python) Workflow executors
+    router.py              # Workflow router
+    orchestrator.py        # Workflow orchestrator
+    chaining_executor.py   # Sequential chain execution
+    parallelization_executor.py  # Parallel task execution
+    difficulty_integration.py    # Difficulty-aware routing
+  agents/
+    skill_enhanced_agent.py  # Skill-enhanced agent (Python)
+  state/
+    simple_checkpoint.py     # State checkpointing (Python)
+  types/
+    langchain.d.ts        # LangChain type declarations
+  utils/                   # (referenced from index.ts exports)
+    tokenUtils.ts          # Token counting and estimation
+
+python/
+  a3m/                    # Python SDK for A3M Router
+  tmlpd.py                # TMLPD Python client
+  examples.py             # Usage examples
+  integrations.py         # Python integration helpers
+
+mcp-server/               # MCP (Model Context Protocol) server for AI agent integration
+integrations/             # Additional integration entry points
+eval/                     # Evaluation framework and benchmarks
+test/ tests/              # Test suites (TypeScript + Python)
+docs/                     # GitHub Pages documentation site
+demo/                     # Demo scripts and recordings
+```
+
+## Key Components
+
+### 1. Ensemble Voting (P0)
+
+The unique differentiator. Routes the same query to multiple providers in parallel, then merges responses using confidence-weighted voting. No other LLM router does this — everyone does sequential fallback (try A, then B, then C).
+
+The ensemble flow:
+1. Query enters the routing engine
+2. Classifier extracts features (complexity, domain, length, code/math presence)
+3. Top-N candidate models selected by tier, cost, and quality profile
+4. Query dispatched to all N providers in parallel
+5. Responses collected and merged with confidence weighting
+6. Best merged result returned with fallback alternatives
+
+### 2. Query Classification
+
+The routing engine (`sdk.ts` → `extractQueryFeatures`) classifies queries on 10+ signals:
+
+| Signal | Description |
+|--------|-------------|
+| complexity | 0.0–1.0, based on keyword density and reasoning indicators |
+| has_code | Code block or programming keyword presence |
+| has_math | Mathematical expression detection |
+| is_multilingual | Non-English character ratio |
+| is_translation | Translation verb detection |
+| is_creative | Creative writing indicators |
+| requires_reasoning | Step-by-step reasoning triggers |
+| domain | Detected domain (legal, medical, security, finance, devops, data) |
+
+Classification routes to the `free` / `cheap` / `mid` / `premium` cost tier, targeting 70.32 accuracy within +/-1 tier (RouterArena score (#1 of 19 routers, arXiv:2510.00202)).
+
+### 3. Memory System
+
+The `MemoryTree` (`memory/memoryTree.ts`) canonicalizes data into ≤3k-token chunks, scores each by relevance, and builds hierarchical summary trees. Supports:
+- **Search**: keyword matching with score ranking
+- **Context retrieval**: top-scored chunks for routing enrichment
+- **Obsidian export**: markdown serialization
+- **Stats**: tree depth, chunk count, memory utilization
+
+Python memory variants (`agentic_memory.py`, `semantic_memory.py`, `working_memory.py`) provide agent-specific memory stores for the orchestration layer.
+
+### 4. Provider Routing
+
+The provider system (`providers/providerConfig.ts`) defines 47+ providers across five tiers:
+
+| Tier | Providers | Purpose |
+|------|-----------|---------|
+| free | Ollama, LM Studio, vLLM, Google (free tier), NVIDIA NIM | Local / zero-cost |
+| cheap | Groq, Cerebras, DeepInfra, Together, Fireworks, Novita, SambaNova, Anyscale, Replicate | Inference-optimized |
+| mid | DeepSeek, Mistral, Perplexity, Cohere, AI21, Qwen (DashScope), StepFun | Good quality/price |
+| premium | OpenAI, Anthropic, xAI (Grok) | Frontier models |
+| enterprise | Azure OpenAI, AWS Bedrock, Google Vertex | Cloud-managed |
+
+Each provider has:
+- `baseUrl`, `apiKeyEnv` (env var name), `models` list
+- `costPerK` (input/output), `tier`, `format` (openai/anthropic/google/cohere/aws-bedrock/google-vertex)
+- `type` (api/cli/local), `priority` (selection order), `maxTokens`
+
+Configuration sources (in priority order):
+1. Environment variables (`*_API_KEY`)
+2. `~/.config/a3m-router/providers.json`
+3. Runtime registration via `registerProvider()`
+
+### 5. Security (Guardrails Engine)
+
+The `GuardrailEngine` (`security/guardrails.ts`) provides configurable input/output checks:
+- **Prompt injection**: score-based detection (0–100)
+- **PII detection and redaction**: emails, phones, SSNs, credit cards, IPs
+- **Content filtering**: configurable blocklist, regex patterns
+- **Language detection**: for intelligent routing decisions
+- **Output validation**: quality checks, hallucination detection
+- **Custom guardrails**: user-defined check functions
+
+### 6. Observability
+
+Three subsystems:
+- **Tracer**: distributed tracing with span creation, completion, and route trace construction
+- **MetricsCollector**: runtime metrics — request counts, latencies, error rates, cache hit rates
+- **Middlewares**: Express-style `observabilityMiddleware`, `observabilityPlugin`, `budgetAlertMiddleware`
+
+### 7. Semantic Cache
+
+Embedding-based cache (`cache/semanticCache.ts`) stores query-response pairs. On lookup, computes cosine similarity against stored embeddings. Supports configurable threshold (default 0.92), TTL, LRU eviction (1000 entries), and multiple embedders (nomic via Ollama, OpenAI, or local).
+
+### 8. Cost Tracking
+
+Tiered cost management:
+- **CostTracker**: per-request recording with provider, model, tokens, latency
+- **CostAnalytics**: savings reports, monthly projections, provider breakdowns, CSV/JSON export
+- **BudgetEnforcer**: hard budget caps with pre-request checks and alerts
+
+### 9. Proxy Server
+
+OpenAI-compatible HTTP proxy (`server/proxyServer.ts`) using only Node.js built-in `http` module. Endpoints:
+- `POST /v1/chat/completions` — OpenAI-compatible chat
+- `POST /v1/completions` — Text completions
+- `GET /v1/models` — Available models
+- `GET /health` — Provider health status
+
+Any OpenAI SDK can point to this proxy to get A3M routing automatically.
+
+### 10. HALO Orchestration (Python)
+
+Hierarchical Autonomous Logic-Oriented Orchestration based on arXiv:2505.13516. Three tiers:
+
+1. **TaskPlanner**: decomposes complex tasks into subtasks with dependency resolution
+2. **RoleAssigner**: assigns specialized agents (roles) to each subtask
+3. **ExecutionEngine**: executes subtasks in parallel with verification and adaptive refinement
+
+Optionally uses **MCTS** (Monte Carlo Tree Search) to explore different execution strategies and learn optimal workflows per task type.
+
+### 11. MCP Server
+
+Model Context Protocol server for AI agent integration. Allows AI agents (Claude, etc.) to use the A3M Router as a tool for parallel multi-LLM execution.
+
+### 12. LangChain Integration
+
+`A3MChatModel` (`integrations/langchainAdapter.ts`) is a drop-in replacement for `ChatOpenAI`. Routes all LLM calls through A3M for cost optimization and intelligent provider selection. Supports streaming, tool calling, and batch processing.
+
+## Data Flow
+
+```
+1. User sends query (via SDK, proxy, CLI, TUI, or LangChain)
+2. GuardrailsEngine checks input (injection, PII, content, length)
+3. SemanticCache looks up embedding match (skip if cache hit)
+4. RoutingEngine classifies query (complexity, domain, features)
+5. Router selects optimal provider(s) using:
+   - Learned quality profiles (UniversalModelRouter)
+   - Cost constraints (BudgetEnforcer)
+   - Retry configuration (ProviderRetryHandler)
+6. (Optional) Multiple providers called in parallel for ensemble voting
+7. ProviderRetryHandler executes with exponential backoff + jitter
+8. GuardrailsEngine validates output
+9. Response returned + recorded in:
+   - CostTracker (per-request cost)
+   - CostAnalytics (aggregate stats)
+   - Observability (tracing + metrics)
+   - SemanticCache (store for future hits)
+   - MemoryTree (context enrichment)
+```
+
+## Design Decisions and Trade-offs
+
+| Decision | Rationale | Trade-off |
+|----------|-----------|-----------|
+| **TypeScript primary** | npm ecosystem reach, serverless compatibility, Vercel/Netlify/Cloudflare Workers | Python users need separate SDK |
+| **Node.js built-in http** for proxy | Zero dependencies, 19.5 KB total bundle | Less feature-rich than Express |
+| **Embedding-based cache** | Semantic similarity beats exact-match for LLM queries | Requires Ollama or OpenAI embedder |
+| **Per-provider retry config** | Chinese providers need longer timeouts + more retries (network latency, rate limits) | More config surface |
+| **In-memory storage** | Zero infra, instant setup, 19.5 KB | No persistence across restarts (memory tree serializable to markdown) |
+| **Online learning (Python router)** | Adapts to unseen models and changing quality | Requires feedback loop, cold start with heuristics |
+| **MCTS for workflow search** | Finds optimal strategies for complex tasks | 3-10x slower than greedy for simple tasks |
+| **47+ baked-in providers** | Zero-config multi-provider out of box | Maintenance burden as APIs change |
+
+## Extension Points
+
+### Adding a New Provider
+
+```typescript
+import { registerProvider, ProviderDefinition } from 'adaptive-memory-multi-model-router';
+
+registerProvider('my-provider', {
+  name: 'My Provider',
+  baseUrl: 'https://api.myprovider.com/v1/chat/completions',
+  apiKeyEnv: 'MY_PROVIDER_API_KEY',
+  models: ['model-name'],
+  costPerK: { input: 1.0, output: 2.0 },
+  tier: 'mid',       // free | cheap | mid | premium | enterprise
+  format: 'openai',  // openai | anthropic | google | cohere | aws-bedrock | google-vertex
+  type: 'api',       // api | cli | local
+  priority: 15,
+  maxTokens: 8192,
+});
+```
+
+Or via config file at `~/.config/a3m-router/providers.json`:
+```json
+{
+  "providers": {
+    "my-provider": {
+      "name": "My Provider",
+      "baseUrl": "https://api.myprovider.com/v1/chat/completions",
+      "apiKeyEnv": "MY_PROVIDER_API_KEY",
+      "models": ["model-name"],
+      "tier": "mid"
+    }
+  }
+}
+```
+
+### Adding a Custom Retry Strategy
+
+```typescript
+import { createRetryHandler } from 'adaptive-memory-multi-model-router';
+
+const handler = createRetryHandler({
+  'my-slow-provider': {
+    timeout: 60000,
+    retry: { maxRetries: 5, initialDelayMs: 5000 },
+  },
+});
+```
+
+### Adding Custom Guardrails
+
+```typescript
+import { GuardrailEngine } from 'adaptive-memory-multi-model-router';
+
+const guardrails = new GuardrailEngine({
+  userGuardrails: [
+    (content) => ({
+      passed: !content.includes('blocked-term'),
+      blocked: content.includes('blocked-term'),
+      reason: content.includes('blocked-term') ? 'Blocked term detected' : undefined,
+    }),
+  ],
+});
+```
+
+### Adding Ensemble Voting Strategies
+
+The ensemble system is extensible by adding new voting strategies to the parallel execution pipeline. Current strategy: confidence-weighted average across multiple provider responses.
+
+### Custom Routing Strategies
+
+The `UniversalModelRouter` (Python) learns routing profiles from execution data. To implement a custom strategy:
+1. Subclass or wrap `routeQuery` in TypeScript
+2. Or extend `UniversalModelRouter._calculate_combined_score` in Python
+3. Register custom feature extractors via `extractQueryFeatures`
+
+### MCP Server Extensions
+
+The MCP server at `mcp-server/` exposes routing as tools. Add tools by extending the MCP tool definitions.

package/AUDIT_REPORT.md

@@ -0,0 +1,28 @@
+# Dependency Audit Report
+
+**Date:** 2026-05-28
+**Project:** adaptive-memory-multi-model-router (v2.13.18)
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total dependencies | 5 (3 prod + 2 dev) |
+| Vulnerabilities | 0 (none found) |
+| Outdated packages | 1 updated |
+
+## Vulnerabilities
+
+**0 vulnerabilities found.** The dependency tree is clean with no reported security issues across all direct and transitive dependencies.
+
+## Updated Packages
+
+| Package | From | To | Type | Reason |
+|---------|------|----|------|--------|
+| `@types/node` | 25.8.0 | 25.9.1 | devDependency | Updated via `npm update` within `^25.8.0` semver range |
+
+## Notes
+
+- `@langchain/core` is listed as `MISSING` in `npm outdated` output — this is expected. It is an **optional peer dependency** (`"optional": true` in `peerDependenciesMeta`) and is not required for core functionality.
+- All other dependencies (`blessed@0.1.81`, `nanoid@5.1.11`, `typescript@6.0.3`) are up-to-date within their semver ranges.
+- No breaking changes were introduced — `npm update` only applied compatible version bumps within declared semver ranges.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[Sdas22@gmail.com](mailto:Sdas22@gmail.com).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to A3M Router
+
+Thanks for helping build the fastest-growing open-source LLM router! 🚀
+
+## Quick Setup
+
+```bash
+git clone https://github.com/Das-rebel/a3m-router.git
+cd a3m-router
+npm install
+npm run build
+```
+
+## Project Structure
+
+```
+src/
+├── providers/     # 47+ LLM provider configurations
+├── routing/       # UCB1 + MCTS routing engine
+├── cache/         # Semantic deduplication cache
+├── proxy/         # OpenAI-compatible proxy server
+└── tui/           # Terminal UI overlay
+```
+
+## Development
+
+```bash
+npm run build      # Compile TypeScript
+npm test           # Run tests
+node dist/tui/dashboard.js  # Launch TUI
+```
+
+## PR Guidelines
+
+- Keep the package under 20KB (no ML deps)
+- Add provider configs in `src/providers/`
+- Route logic in `src/routing/`
+- TUI changes in `src/tui/`
+- Update CHANGELOG.md
+
+## Adding a Provider
+
+1. Add config in `src/providers/providerConfig.ts`
+2. Set tier: `free` / `cheap` / `mid` / `premium`
+3. Add to `PROVIDER_TIERS` map
+4. PR with latency benchmarks
+
+## Questions?
+
+Open an issue or reach out on [GitHub Discussions](https://github.com/Das-rebel/a3m-router/discussions).

package/CONTRIBUTORS.md

@@ -0,0 +1,20 @@
+# Contributors ✨
+
+Thanks to everyone who has contributed to A3M Router!
+
+## Core Team
+- **Megha Mukherjee** — Creator & Lead Developer
+  - Parallel ensemble architecture
+  - Provider routing system
+  - Confidence scoring algorithm
+
+## Contributors
+<!-- 
+Add yourself here! Open a PR with your name and contribution.
+Format: - [Name](https://github.com/username) — What you contributed
+-->
+
+## Special Thanks
+- The open-source LLM community
+- Everyone who starred, forked, or shared the project
+- npm downloaders (10K+ and counting! ❤️)

package/Dockerfile

@@ -0,0 +1,53 @@
+# =============================================================================
+# A3M Router — Adaptive Memory Multi-Model Router
+# Multi-stage Docker build for minimal production image
+# =============================================================================
+
+# ---------------------------------------------------------------------------
+# Stage 1: Build
+# ---------------------------------------------------------------------------
+FROM node:20-slim AS build
+
+WORKDIR /app
+
+# Copy package manifests first for layer caching
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Copy source code
+COPY tsconfig.json tsconfig.build.json ./
+COPY src/ src/
+
+# Build TypeScript → dist/
+RUN npm run build
+
+# Prune dev dependencies (optional, to keep only production deps if any)
+# RUN npm prune --production
+
+# ---------------------------------------------------------------------------
+# Stage 2: Run
+# ---------------------------------------------------------------------------
+FROM node:20-alpine AS run
+
+WORKDIR /app
+
+# Create non-root user for security
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+
+# Copy built artifacts from build stage
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+
+# Default port for the A3M Router API/health endpoint
+EXPOSE 3000
+
+# Switch to non-root user
+USER appuser
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+# Default command — start the main router server
+CMD ["node", "dist/index.js"]

package/Dockerfile.proxy

@@ -0,0 +1,33 @@
+# =============================================================================
+# A3M Router — OpenAI-Compatible Proxy
+# Standalone proxy service for OpenAI-compatible API routing via A3M
+# =============================================================================
+
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Create non-root user
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+
+# Copy proxy package manifests for layer caching
+COPY proxy/package*.json ./
+
+# Install production dependencies only
+RUN npm ci --production
+
+# Copy proxy source code
+COPY proxy/ ./
+
+# OpenAI-compatible proxy default port
+EXPOSE 8787
+
+# Switch to non-root user
+USER appuser
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:8787/health || exit 1
+
+# Start proxy server
+CMD ["node", "server.js"]