murm 0.2.0__tar.gz

murm-0.2.0/.env.example

@@ -0,0 +1,55 @@
+# MURM environment configuration
+# Copy to .env and fill in your values.
+# All fields have sensible defaults except LLM_API_KEY.
+
+
+# LLM provider (orchestration: graph building, report generation)
+# Any model string litellm understands works here.
+#
+# Examples:
+#   gpt-4o-mini                              (OpenAI)
+#   claude-3-5-haiku-20241022                (Anthropic)
+#   groq/llama-3.1-70b-versatile            (Groq — fast and cheap)
+#   ollama/llama3.2                          (local Ollama)
+#   azure/gpt-4o                             (Azure OpenAI)
+#   anthropic/claude-3-haiku-20240307        (Anthropic via litellm prefix)
+
+LLM_MODEL=gpt-4o-mini
+LLM_API_KEY=your_api_key_here
+# Only needed if your provider uses a custom base URL (e.g. Azure, local proxy)
+# LLM_BASE_URL=https://your-endpoint.openai.azure.com/
+
+
+# Agent model (per-agent inference inside simulation rounds)
+# Can be a cheaper/faster model than the orchestration LLM.
+# Defaults to LLM_MODEL if not set.
+
+# AGENT_MODEL=groq/llama-3.1-8b-instant
+# AGENT_API_KEY=your_groq_key_here
+
+
+# Token budget (0 = unlimited)
+# Set to a positive integer to cap cumulative token spend per process.
+# The API returns an error if the budget is exceeded mid-run.
+# Useful for cost control during development.
+
+TOKEN_BUDGET=0
+
+# Storage — all local, no external services required
+
+DATA_DIR=data
+CHROMA_PATH=data/chroma
+
+# API server
+API_HOST=0.0.0.0
+API_PORT=8000
+# Comma-separated list of allowed CORS origins for the frontend
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# Simulation defaults (all overridable per-run via API or CLI)
+DEFAULT_AGENTS=50
+DEFAULT_ROUNDS=30
+DEFAULT_SEED=42
+
+# Logging
+LOG_LEVEL=INFO

murm-0.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

murm-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to MURM
+
+## Development setup
+
+```bash
+git clone https://github.com/AM-2304/murm
+cd murm
+pip install -e ".[dev]"
+cp .env.example .env
+```
+
+Set at minimum `LLM_API_KEY` and `LLM_MODEL` in `.env`. Any LiteLLM-compatible model string works.
+
+## Running tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+The test suite covers all deterministic components and requires no LLM API key. Tests that invoke the LLM are integration tests and are not part of the default suite.
+
+## Code style
+
+```bash
+python -m ruff check murm/
+python -m ruff format murm/
+```
+
+## Project structure for contributors
+
+Each module has a single responsibility. The dependency graph flows strictly downward:
+
+```
+config.py
+  ↓
+llm/ (provider, budget)
+  ↓
+graph/ (engine, embedder, extractor)
+agents/ (model, generator)
+  ↓
+simulation/ (engine, environment, metrics, trace)
+  ↓
+analysis/ (report_agent, calibration)
+  ↓
+api/ (store, app, routes)
+cli.py
+```
+
+Nothing in `simulation/` imports from `api/`. Nothing in `graph/` imports from `agents/`. Circular imports will break the test suite.
+
+## Adding a new environment
+
+Create a class in `murm/simulation/environment.py` that extends `Environment` and implements three methods:
+
+```python
+class MyEnvironment(Environment):
+    def get_context_feed(self, round_num: int, max_items: int = 10) -> list[str]: ...
+    def ingest_action(self, action: dict) -> None: ...
+    def inject_external_event(self, content: str, source: str, round_num: int) -> None: ...
+    def get_all_posts(self) -> list[dict]: ...
+```
+
+Register it in the `build_environment()` factory dict.
+
+## Adding a new emergence metric
+
+Add a function to `murm/simulation/metrics.py` following the pattern of the existing helpers. Call it inside `MetricsCollector.record_round()` and include the result in the returned dict. Add a corresponding test in `tests/test_core.py`.
+
+## Pull request checklist
+
+- [ ] All existing tests pass (`pytest tests/`)
+- [ ] New functionality has tests
+- [ ] No circular imports introduced
+- [ ] No hardcoded API keys, model names, or file paths
+- [ ] Comments in English only
+- [ ] No emojis in code or comments
+
+## Reporting issues
+
+Please include: OS, Python version, LLM provider and model, the exact error message, and the minimum seed text that reproduces the issue. Issues without reproduction steps will be triaged last.

murm-0.2.0/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+COPY README.md .
+COPY murm/ murm/
+
+RUN pip install --no-cache-dir -e . \
+    && python -c "from chromadb import PersistentClient"
+
+EXPOSE 8000
+
+CMD ["uvicorn", "murm.main:app", "--host", "0.0.0.0", "--port", "8000"]

murm-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akhilesh M
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

murm-0.2.0/PARAMETERS.md

@@ -0,0 +1,224 @@
+# MURM COMPLETE PARAMETER REFERENCE
+ Every tunable value in the system, where it lives, what it does, and what changing it affects.
+
+## TIER 1: .env FILE: Global defaults, no code change needed
+
+### DEFAULT_AGENTS=50
+ File: config.py -> Settings.default_agents
+ What: Pre-fills the agent count in the UI and CLI default.
+ Effect: More agents = more diverse opinions, more LLM calls, higher cost.
+         Recommendation: Use 20 for testing, 50-100 for real runs.
+         Rule of thumb: double agents = double cost, diminishing returns above 100.
+
+### DEFAULT_ROUNDS=30
+ File: config.py -> Settings.default_rounds
+ What: Pre-fills the rounds slider in the UI.
+ Effect: More rounds = more interaction cycles, slower convergence detection.
+         Recommendation: Use 15 for testing, 30-50 for real runs.
+
+### DEFAULT_SEED=42
+ File: config.py -> Settings.default_seed
+ What: The starting number for all randomness in the simulation.
+ Effect: Same seed + same inputs = identical output every time.
+         Change this to get a different-but-reproducible run.
+
+### TOKEN_BUDGET=0
+ File: config.py -> Settings.token_budget
+ What: Hard cap on total tokens across the entire process.
+ Effect: 0 = no limit. Any positive integer stops the run if exceeded.
+         200000 tokens ≈ $0.02 on Groq, $0.06 on gpt-4o-mini.
+
+### LOG_LEVEL=INFO
+ File: config.py -> Settings.log_level
+ What: How much detail appears in your terminal.
+ Values: DEBUG (every LLM call), INFO (normal), WARNING (errors only)
+ Recommendation: Use DEBUG when something is not working.
+
+## TIER 2: API REQUEST BODY: Per-run overrides
+
+ These are the values you set in the UI or pass in the API request body.
+ They override the .env defaults for a single run only.
+
+ ### n_agents: 5-500
+   UI: "Agents" slider in RunForm
+   API: {"n_agents": 30}
+   CLI: --agents 30
+
+ ### n_rounds: 5-200
+   UI: "Rounds" slider in RunForm
+   API: {"n_rounds": 20}
+   CLI: --rounds 20
+
+ ### seed: any integer
+   UI: "Random seed" field
+   API: {"seed": 99}
+   CLI: --seed 99
+
+ ### n_sensitivity_seeds: 1-5
+   UI: "Sensitivity seeds" field
+   API: {"n_sensitivity_seeds": 3}
+   CLI: --seeds 3
+   Effect: Runs the simulation N times with seed, seed+1, seed+2...
+           and produces an uncertainty statement comparing outcomes.
+
+ ### environment_type: "forum" or "town_hall"
+   UI: "Environment" dropdown
+   API: {"environment_type": "town_hall"}
+   CLI: --env town_hall
+   Effect: forum = open discussion noticeboard
+           town_hall = structured agenda, each round is an agenda item
+
+ ### opinion_distribution: "normal", "bimodal", "power_law", "uniform"
+   UI: "Opinion distribution" dropdown
+   API: {"opinion_distribution": "bimodal"}
+   CLI: --opinion-dist bimodal
+   Effect: Controls starting stance spread across the population.
+
+ ### skip_graph: true or false
+   UI: not in UI yet (API and CLI only)
+   API: {"skip_graph": true}
+   CLI: --skip-graph
+   Effect: Bypasses knowledge graph extraction. Faster but agents
+           have no factual grounding — more hallucination risk.
+
+ ### counterfactual_events: list of {round, content, source}
+   UI: "Counterfactual events" builder in RunForm
+   API: {"counterfactual_events": [{"round": 10, "content": "New study contradicts claims", "source": "Reuters"}]}
+   CLI: not available (use API directly for this)
+
+## TIER 3: CODE CONSTANTS: Structural changes, edit the source
+
+ ### Agent influence role distribution
+ File: murm/agents/generator.py, line ~35
+ Variable: _INFLUENCE_ROLE_WEIGHTS
+ Current values:
+   INFLUENCER: 5%     (high reach, infrequent posting)
+   ACTIVE_USER: 25%   (moderate reach and frequency)
+   PASSIVE_USER: 55%  (low reach, mostly reactive)
+   SKEPTIC: 10%       (challenges dominant narratives)
+   AMPLIFIER: 5%      (reposts/shares, low original content)
+ Change to: reflect your domain's actual participation pattern.
+ 
+### Example for a scientific community:
+   _INFLUENCE_ROLE_WEIGHTS = {
+       InfluenceRole.INFLUENCER: 0.03,
+       InfluenceRole.ACTIVE_USER: 0.40,
+       InfluenceRole.PASSIVE_USER: 0.35,
+       InfluenceRole.SKEPTIC: 0.15,
+       InfluenceRole.AMPLIFIER: 0.07,
+   }
+
+### Opinion scale definitions
+ File: murm/agents/model.py
+ Enum: OpinionBias
+ Current: strongly_agree, agree, neutral, disagree, strongly_disagree
+ To add a domain-specific scale (e.g. for financial sentiment):
+   class OpinionBias(str, Enum):
+       BULLISH = "bullish"
+       CAUTIOUSLY_BULLISH = "cautiously_bullish"
+       NEUTRAL = "neutral"
+       CAUTIOUSLY_BEARISH = "cautiously_bearish"
+       BEARISH = "bearish"
+ Then update _OPINION_VALUES in metrics.py accordingly.
+
+### Environment context feed size
+ File: murm/simulation/environment.py
+ Method: get_context_feed(self, round_num, max_items=10)
+ Default: 10 posts visible to each agent per round
+ Effect: More = richer context but longer prompts and higher cost.
+         Less = faster and cheaper but agents have less to react to.
+### To change globally:
+   def get_context_feed(self, round_num: int, max_items: int = 5) -> list[str]:
+
+### RAG context per agent turn
+ File: murm/simulation/engine.py, inside _agent_turn method
+ Variable: top_k in embedder.query call (currently 3)
+ Effect: How many knowledge graph facts each agent sees per turn.
+         Increase to reduce hallucination, at the cost of longer prompts.
+### Current:
+   hits = self._embedder.query(state.last_action_summary, top_k=3)
+ Change to top_k=5 for better grounding, top_k=1 for minimal cost.
+
+### Distance threshold for RAG facts
+ File: murm/simulation/engine.py, inside _agent_turn method
+ Current: h["distance"] < 0.8 (filters out loosely related facts)
+ Lower value = stricter matching (only very relevant facts shown)
+ Higher value = looser matching (more facts shown, some less relevant)
+ Change: h["distance"] < 0.6 for strict, h["distance"] < 0.9 for loose
+
+### ReACT report agent iteration limit
+ File: murm/analysis/report_agent.py
+ Variable: MAX_REACT_ITERATIONS = 12
+ Effect: Maximum number of tool calls before the report is written.
+         Increase for more thorough analysis (more cost).
+         Decrease for faster, cheaper but shallower reports.
+
+### Sensitivity variance thresholds
+ File: murm/analysis/calibration.py
+ Function: _variance_label(std: float) -> str
+ Current: low < 0.05, medium 0.05-0.15, high > 0.15
+ Adjust to match your domain's expected variance.
+
+### Entropy convergence detection
+ File: murm/simulation/metrics.py
+ Variable: _ENTROPY_CONVERGENCE_THRESHOLD = 0.05
+ Effect: How stable opinion entropy must be (for 3 consecutive rounds)
+         before the system declares the simulation has "settled."
+
+### Maximum concurrent agents per round
+ File: murm/simulation/engine.py
+ Class: SimulationConfig
+ Field: max_concurrent_agents: int = 10
+ Effect: How many agent LLM calls run in parallel.
+         Higher = faster simulation but more API rate limit risk.
+         Lower = safer but slower.
+ Change in the API request body: {"max_concurrent_agents": 5}
+ Or modify the dataclass default directly.
+
+## TIER 4: PERSONA PROMPT: Change what kind of person is generated
+
+ File: murm/agents/generator.py
+ Variable: _PERSONA_SYSTEM (the system prompt for persona generation)
+ Current: generates socially diverse archetypes via randomly seeded demographics
+          (e.g., "Gen Z College Student", "Rural Small Business Owner")
+ To create domain-specific personas, change the system prompt.
+
+### Example for financial analysts:
+   _PERSONA_SYSTEM = """You are creating realistic financial market participants.
+   Generate exactly ONE person profile as valid JSON.
+   The person must have genuine financial market experience.
+   Their opinion reflects their portfolio position and risk tolerance.
+   ... """
+
+### Example for policy stakeholders:
+   _PERSONA_SYSTEM = """You are creating realistic policy stakeholders.
+   Each person represents a real constituency: NGO worker, small business owner,
+   academic researcher, government official, affected community member, etc.
+   ... """
+
+## TIER 5: AGENT ACTION PROMPT: What agents actually DO each round
+
+ File: murm/simulation/engine.py
+ Variable: _AGENT_SYSTEM (the system prompt governing agent behavior)
+ Current: Simulates social media users (post, reply, share, abstain)
+
+### To simulate policy deliberation (not social media):
+   _AGENT_SYSTEM = """You are simulating a stakeholder in a policy consultation.
+   Stay completely in character. Respond ONLY with valid JSON:
+   {
+     "action": "statement" | "question" | "objection" | "support" | "abstain",
+     "content": "your spoken contribution (empty string if abstaining)",
+     "opinion_shift": "strongly_agree|agree|neutral|disagree|strongly_disagree or null",
+     "reasoning": "1 sentence internal justification"
+   }
+   opinion_shift reflects your stance AFTER the discussion — null if unchanged."""
+
+### To simulate financial market commentary:
+   _AGENT_SYSTEM = """You are simulating a financial market participant.
+   Respond ONLY with valid JSON:
+   {
+     "action": "buy_signal" | "sell_signal" | "hold" | "comment" | "abstain",
+     "content": "your public comment or analysis",
+     "opinion_shift": "bullish|cautiously_bullish|neutral|cautiously_bearish|bearish or null",
+     "reasoning": "1 sentence rationale"
+   }"""