mars-cmbagent 1.0.0

MARS CMBAgent - multi-agent system for autonomous discovery, powered by ag2

MARS

Multi-Agent Research System

Turn complex work into automated, multi-agent workflows.
From market insights to research papers — define a task, pick a mode, let the agents deliver.

Modes  •  Tasks  •  Use Cases  •  Getting Started  •  Architecture

MARS orchestrates 50+ specialized AI agents — planners, coders, researchers, reviewers, web surfers, OCR processors — powered by AG2 (AutoGen 2). Give it a task, choose how agents should work (the mode), and get back deliverables: reports, code reviews, research papers, product strategies, weekly briefings, or anything you can define.

Why MARS?

Complex work involves too many steps — gathering information, analyzing data, writing reports, iterating on feedback. MARS handles the heavy lifting so you can focus on decisions that matter.

8 composable modes Single-pass, multi-step planning, hypothesis generation, document extraction, literature review, input enrichment, human-in-the-loop, copilot. Mix and match to build any workflow.	50+ specialized agents Planning, coding, web search, literature retrieval, critical evaluation, and document processing — orchestrated in pipelines that carry context across every phase.
Pre-built tasks, unlimited custom ones Ship with templates for deep research, AI weekly reports, code review, product discovery, and release notes. Build your own with the Task Builder.	Human-in-the-loop or fully autonomous Review and approve agent plans at every step, or let MARS run end-to-end on its own. Your choice, per task.

---

🔀 Modes

Modes define how agents approach a task. They are the building blocks — combine any mode with different agents and configurations to create unlimited automated workflows.

Mode	What It Does	Good For
Single-Pass Analysis one-shot	One agent, one pass, no iterative planning. Fast and direct.	Quick analysis, code gen, report drafts, release notes, one-off scripts
Multi-Step Research planning-control	Planner creates a plan, reviewer validates, execution agents carry it out step by step with context across phases.	Market research, competitive intelligence, technical investigations, multi-part analyses
Hypothesis Generation idea-generation	idea_maker proposes, idea_hater critiques — adversarial loop that stress-tests ideas before you commit.	Product brainstorming, strategic planning, research directions, design exploration
Document Extraction ocr	Mistral OCR extracts structured text from PDFs, scans, handwritten notes, and figures.	Digitizing documents, extracting tables from reports, processing scanned records
Literature Review arxiv	Downloads papers, extracts content, summarizes findings and citations.	Lit reviews, finding related work, surveying a field, annotated bibliographies
Input Enrichment enhance-input	Auto-downloads referenced documents, runs OCR and summarization, enriches your input before agents start working.	Tasks with external references, multi-source context, pre-processing for deeper analysis
Human-in-the-Loop hitl-interactive	Approval checkpoints at every decision point. Agents propose, you approve, then they execute.	High-stakes work, expert-guided analysis, exploratory research, full-control workflows
Copilot Chat copilot	Conversational interface with persistent context. Ask follow-ups, redirect, iterate in real time.	Exploratory analysis, iterative problem-solving, rapid prototyping, guided sessions

Copilot workflow presets

Preset	Behavior
Copilot Assistant	Adapts to complexity. Plans when needed, asks approval after each step.
Interactive Session	Continuous back-and-forth. Up to 50 turns.
Quick Task	Direct execution. No planning, no approval.
Interactive Copilot	Proposes actions first, waits for your input before executing.

---

📋 Tasks

Tasks are where modes become deliverables. Each task = a mode + agents + configuration = a specific output. MARS ships with pre-built templates, and the Task Builder lets you create as many custom ones as you need.

Pre-Built Templates

Deep Scientific Research	deep-research	4-stage pipeline: idea generation → method development → experiments → LaTeX paper. Adversarial review built in. Review and refine between every stage.
AI Weekly Report	hitl-interactive	Weekly technology briefings with human approval at each step. Planner outlines, researcher gathers, engineer compiles.
Code Review	planning-control	Multi-dimensional code analysis: correctness, performance, security, style. Plans review strategy first, then executes.
Release Notes	one-shot	Reads Git history, categorizes changes, produces readable release documentation.
Product Discovery	one-shot	Full workshop flow: client analysis → problem definition → opportunities → solutions → features → builder prompts.

Build Your Own

The modes are building blocks. Combine any mode + agent set + config to automate whatever you need:

Task Idea	Mode	Deliverable
Competitive Landscape Report	planning-control	Structured competitor comparison
Patent Prior Art Search	arxiv + enhance-input	Summarized prior art from publications
Technical Due Diligence	hitl-interactive	Codebase/system analysis with checkpoints
Weekly Market Digest	hitl-interactive	Recurring market trend briefings
Research Paper	deep-research	Full LaTeX paper from idea to PDF
Onboarding Guide Generator	one-shot	Repo documentation for new team members
Customer Feedback Synthesis	idea-generation	Ranked hypotheses about user pain points

Task Builder lets you configure:

Task Name       →  What you want done
Execution Mode  →  Any of the 8 modes
Model           →  GPT-4o, Claude, Gemini, etc.
Max Rounds      →  1–100 agent turns
Approval Mode   →  none | always | on-failure

---

🚀 What You Can Build

Automate Recurring Deliverables Weekly reports, market digests, release notes, competitive updates — set up once, run on demand. Same multi-agent pipeline, consistent output every time. Generate Market Insights Multi-Step Research mode + web search + doc retrieval. Planner breaks work into phases, researchers gather data, engineer compiles the final report. Run Product Discovery Automate the entire workshop — client analysis, problem definition, opportunities, solutions, features. Start with the template, iterate with Copilot. Write Research Papers Idea → adversarial review → methodology → experiments → compiled LaTeX PDF. Review and refine between every stage of the Deep Research pipeline.

Literature Discovery & Synthesis Agents search ArXiv, download papers, OCR content, build vector stores. Describe your question, get a structured synthesis. Build Reproducible Pipelines engineer and executor agents run code in sandboxed environments. Every execution tracked with costs, files, and event logs. Re-run with different inputs. Extend With Your Own Tools Pluggable integrations via CrewAI and LangChain. Add domain-specific tools without touching core code. Pre-load RAG agents with your data. Collaborate Interactively Copilot mode for real-time pair-work. Sessions persist context across turns. Multi-step mode carries context across phases — nothing lost.

---

🏗 Architecture

┌─────────────────────────────────────────────────────┐
│                    Frontend (UI)                     │
│          Next.js 14  ·  React 18  ·  TailwindCSS    │
│        Real-time via Socket.IO  ·  DAG Visualizer   │
├─────────────────────────────────────────────────────┤
│                   Backend (API)                      │
│            FastAPI  ·  Uvicorn  ·  WebSockets        │
│     REST endpoints  ·  Task engine  ·  Event stream  │
├─────────────────────────────────────────────────────┤
│               Agent Framework (Core)                 │
│              AG2 multi-agent orchestration            │
│      50+ agents  ·  DAG execution  ·  RAG pipeline   │
├─────────────────────────────────────────────────────┤
│                  Storage & Data                      │
│         SQLAlchemy (SQLite / PostgreSQL)  ·  Alembic │
│        File tracking  ·  Cost records  ·  Events     │
└─────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 14, React 18, TailwindCSS	Web UI with real-time updates
Backend	FastAPI, Uvicorn	REST API + WebSocket server
Agents	AG2 (AutoGen 2)	Multi-agent orchestration
Real-Time	WebSockets, Socket.IO	Live task streaming
Database	SQLAlchemy, SQLite / PostgreSQL	Persistence and tracking
DAG Viz	@xyflow/react	Interactive graph rendering
Tools	CrewAI, LangChain	External tool integrations
Deploy	Docker, Docker Compose	Containerized deployment

---

🤖 Agent System

50+ agents organized by function:

Planning Agent Role planner Plans and breakdowns task_improver Refines descriptions plan_recorder Persists plans plan_reviewer Quality review plan_setter Activates plans

Execution Agent Role engineer Writes code researcher Research & analysis executor Sandboxed code run executor_bash Shell commands installer Package installs

Retrieval Agent Role rag_agents RAG pipelines retrieve_assistant Doc retrieval web_surfer Web browsing perplexity AI search

Utility Agent Role idea_maker Generates ideas idea_hater Critiques ideas summarizer Summarizes output terminator Task completion copilot_control Copilot flow

---

🏁 Getting Started

Prerequisites

• Python >= 3.12   |   Node.js >= 18   |   npm >= 9   |   Git
• At least one LLM API key (OpenAI, Anthropic, Gemini, etc.)

Install

git clone https://github.com/UJ2202/mars_cmbagent.git && cd mars_cmbagent

# Backend
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install -e ".[data]"       # Optional: scipy, matplotlib, xgboost
pip install -e ".[jupyter]"    # Optional: Jupyter support

# Frontend
cd mars-ui && npm install && cd ..

Configure

# .env (project root)
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key     # optional
GEMINI_API_KEY=your-gemini-api-key           # optional
PERPLEXITY_API_KEY=your-perplexity-api-key   # optional
MISTRAL_API_KEY=your-mistral-api-key         # optional

# mars-ui/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8000

Run

# Terminal 1 — Backend
cd backend && python run.py
# → http://localhost:8000  |  Docs: http://localhost:8000/docs

# Terminal 2 — Frontend
cd mars-ui && npm run dev
# → http://localhost:3000

Docker

docker-compose up --build
# or
docker build -t mars . && docker run -p 3000:3000 -p 8000:8000 -e OPENAI_API_KEY=your-key mars

---

📡 API Reference

Full interactive docs at http://localhost:8000/docs.

Method	Endpoint	Description
POST	/tasks	Create a new task
GET	/tasks/{id}	Get task status
POST	/runs	Start a task run
GET	/runs/{id}	Get run details
POST	/sessions	Create a session
POST	/phases/{id}/execute	Execute a workflow phase
POST	/enhance	Enhance a task description
POST	/api/deepresearch/create	Create a deep research task
POST	/api/deepresearch/{id}/stages/{num}/execute	Execute a research stage
POST	/api/arxiv/filter	Extract and download papers
WS	/ws/{task_id}	Real-time updates

WebSocket Events

Event	Description
status	Task status changes
output	Agent output streaming
dag_update	DAG execution progress
approval_request	HITL approval requests
cost_update	Token usage and cost tracking
file_created	New file notifications
error	Error events

---

🔌 External Tools

30+ integrations via CrewAI and LangChain adapters:

ArXiv  ·  Wikipedia  ·  DuckDuckGo  ·  Perplexity  ·  Python REPL  ·  Shell  ·  File Ops  ·  Web Scraping  ·  GitHub Search

---

🧪 Testing

pytest                       # All tests
pytest -m "not slow"         # Skip slow tests
pytest -m integration        # Integration only
pytest -v                    # Verbose

---

Logs  →  ~/.cmbagent/logs/backend.log

License  →  Apache 2.0

---

Maintainers
Ujjwal Tiwari ([e-mail])  ·  Chetana Shanbhag ([e-mail])  ·  CMBAgents ([e-mail])

Contributors
@SACHIN-MOURYA  ·  @khapraravi