modular-studio 0.2.4 → 1.0.0

package/README.md

@@ -1,261 +1,41 @@
-# Modular Studio
-
-> The Context Engineering Layer — an IDE for designing AI agent knowledge pipelines.
-
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
-[![Tests: 646](https://img.shields.io/badge/tests-646_passing-green.svg)]()
-[![Version: 0.2.0](https://img.shields.io/badge/version-0.2.0-blue.svg)]()
-
-## What is this?
-
-Modular Studio is a **context engineering IDE** — a visual workspace for building AI agents through structured knowledge pipelines rather than monolithic prompts.
-
-Instead of writing one massive system prompt and hoping for the best, you design a pipeline:
-
-```
-Sources → Tree Index → Budget Allocator → Agent Navigator → Compress → Context Assembly → LLM
-```
-
-Every source (markdown files, Notion pages, HubSpot records, Slack threads, GitHub repos) becomes a **tree of headings** that an agent navigates per-task, selecting branches at the right depth. An epistemic budget allocator ensures ground-truth sources get priority over hypotheses. The result is dense, relevant context assembled within a token budget.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         Modular Studio IDE                              │
-│                                                                         │
-│  ┌──────────────┐   ┌──────────────────┐   ┌────────────────────────┐  │
-│  │ Sources Panel │   │  Agent Builder    │   │   Test & Export Panel   │  │
-│  │              │   │                  │   │                        │  │
-│  │ Knowledge    │   │ Identity         │   │ Chat Testing           │  │
-│  │ MCP Servers  │   │ Instructions     │   │ Execution Traces       │  │
-│  │ Skills       │   │ Constraints      │   │ Export (6 formats)     │  │
-│  │ Memory       │   │ Workflow         │   │ Security Badges        │  │
-│  │ Fact Insights│   │ Tools            │   │                        │  │
-│  └──────┬───────┘   └────────┬─────────┘   └──────────┬─────────────┘  │
-│         │                    │                         │                │
-│  ───────┴────────────────────┴─────────────────────────┴────────────── │
-│                                                                         │
-│  ┌─────────────────── Context Engineering Pipeline ──────────────────┐  │
-│  │                                                                   │  │
-│  │  Sources ──► Tree    ──► Budget     ──► Agent      ──► Compress  │  │
-│  │             Index       Allocator      Navigator               │  │
-│  │             (4 connectors) (epistemic   (LLM-driven   (semantic  │  │
-│  │                          weights)      branch sel.)   dedup)    │  │
-│  │                              │              │                     │  │
-│  │                              ▼              ▼                     │  │
-│  │                    Contradiction    Corrective Re-Nav             │  │
-│  │                     Detection       + HyDE                       │  │
-│  │                              │              │                     │  │
-│  │                              └──────┬───────┘                     │  │
-│  │                                     ▼                             │  │
-│  │                          Attention-Ordered                        │  │
-│  │                          Context Assembly                         │  │
-│  └───────────────────────────────────────────────────────────────────┘  │
-│                                                                         │
-│  ┌─────────────────── Memory System ─────────────────────────────────┐  │
-│  │  Fact Extraction ──► Three-Factor Retrieval ──► Consolidation    │  │
-│  │  (pattern + LLM)    (relevance + recency       (prune, merge,    │  │
-│  │                      + importance)               promote)         │  │
-│  └───────────────────────────────────────────────────────────────────┘  │
-│                                                                         │
-│  ┌─────────────────── Team Runtime ──────────────────────────────────┐  │
-│  │  POST /api/runtime/team ──► Parallel Agents ──► Shared Facts     │  │
-│  │  (SSE streaming)            (Claude Agent SDK)   (deduplicated)   │  │
-│  └───────────────────────────────────────────────────────────────────┘  │
-│                                                                         │
-│  Backend: Express 5 + TypeScript        Frontend: React 19 + Zustand   │
-│  Port 4800                              Port 5173 (dev)                │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-## Features
-
-### Pipeline
-- **Epistemic Budget Allocator** — Token budgets by knowledge type (ground-truth 30%, evidence 20%, framework 15%, guideline 15%, signal 12%, hypothesis 8%)
-- **4 Source Connectors** — Markdown, Structured, Chronological, Flat — normalize any source to a navigable tree
-- **Agent Navigator** — LLM reads tree headlines and selects relevant branches per task
-- **Attention-Aware Ordering** — Sources reordered to exploit LLM primacy/recency attention bias
-- **Contradiction Detection** — Heuristic entity extraction + epistemic priority resolution, no LLM calls
-- **Context Compression** — Semantic dedup, filler removal, code compression (inspired by [rtk-ai/rtk](https://github.com/rtk-ai/rtk))
-- **Corrective Re-Navigation** — Critique pass identifies gaps, re-navigates with 20% budget cap
-- **HyDE Navigation** — Hypothetical ideal answer improves heading matching for complex queries
-
-### Memory
-- **Fact Extraction** — Pattern-based + LLM-based fact extraction with epistemic typing
-- **Three-Factor Retrieval** — `score = relevance + 0.5×recency + 0.5×importance`
-- **Ebbinghaus Decay** — Strength = importance × e^(-days/halfLife), half-life extends with access frequency
-- **Consolidation** — Prune weak facts, merge similar ones, promote validated hypotheses
-
-### Runtime
-- **Team Execution** — Multi-agent parallel runs with SSE streaming and per-agent system prompts
-- **Cross-Agent Facts** — Extracted facts shared across team members, deduplicated by confidence
-- **Claude Agent SDK** — Full integration with built-in tools (Read, Edit, Bash, Grep, Glob, WebSearch, WebFetch)
-- **Maximizable Results** — Full-screen overlay for reading long agent outputs
-- **Contrastive Retrieval** — For analytical queries, automatically pulls both supporting AND contradicting evidence
-
-### IDE
-- **Knowledge Type System** — 6 types with classification rules and visual color coding
-- **MCP Server Registry** — 100+ pre-configured servers with live health probes
-- **Skills Marketplace** — Searchable catalog with security badges (GEN, Socket, Snyk)
-- **Agent Directory Format** — Primary export: ZIP with agent.yaml + SOUL.md + INSTRUCTIONS.md + TOOLS.md + KNOWLEDGE.md + MEMORY.md. Git-friendly, human-readable, portable.
-- **Universal Export** — Claude Code, Amp, Codex, Vibe Kanban, OpenClaw, Generic JSON
-- **Execution Traces** — Timeline of LLM calls, tool invocations, retrievals
-- **Automatic Versioning** — Semantic diffs on every agent change
-- **AI-Powered Generation** — Generate full agent configs from plain-language descriptions
-
-## Quick Start
-
-```bash
-# Run directly
-npx modular-studio
-
-# Or install globally
-npm install -g modular-studio
-modular-studio
-
-# Development
-git clone https://github.com/VictorGjn/modular-patchbay.git
-cd modular-patchbay
-npm install --legacy-peer-deps
-npm run dev          # Frontend on :5173, backend on :4800
-npm run build:all    # Full production build
-npm test             # 646 tests
-```
-
-### First steps
-
-1. Add an LLM provider (Anthropic, OpenAI, OpenRouter, or Google)
-2. Create an agent — set identity, persona, objectives, constraints
-3. Add knowledge sources — assign knowledge types (ground-truth, evidence, framework, etc.)
-4. Test with the chat panel — the pipeline assembles context automatically
-5. Export to your preferred format (Claude Code, Amp, Codex, etc.)
-
-## Agent Definition Format
-
-```yaml
-version: '1.0'
-kind: agent
-
-identity:
-  name: fleet-monitor
-  display_name: Fleet Monitor
-  description: Real-time vessel performance monitoring agent
-  tags: ['maritime', 'fleet', 'monitoring']
-
-instructions:
-  persona: |
-    You are a maritime fleet performance analyst.
-    Monitor vessel metrics and flag anomalies.
-  constraints:
-    - Never recommend speed changes without fuel impact analysis
-    - Always include CII rating context
-  objectives:
-    primary: Detect performance anomalies early
-    success_criteria:
-      - Flag fuel overconsumption within 4 hours
-      - Correlate weather impact on route efficiency
-
-context:
-  knowledge:
-    - type: file
-      ref: fleet-specs.md
-      knowledge_type: ground-truth
-      depth: 0
-    - type: structured
-      ref: hubspot://deals
-      knowledge_type: signal
-      depth: 2
-
-  mcp_servers:
-    - name: github
-      transport: stdio
-      command: npx @modelcontextprotocol/server-github
-
-workflow:
-  steps:
-    - id: ingest
-      action: Read latest vessel telemetry
-      condition: always
-    - id: analyze
-      action: Compare against baseline performance
-    - id: alert
-      action: Flag anomalies with severity and recommended actions
-```
-
-## Export Targets
-
-| Target | Format | Use case |
-|--------|--------|----------|
-| Claude Code | `AGENTS.md` | Direct CLI integration |
-| Amp | YAML | Sourcegraph agent definitions |
-| Codex | JSON | OpenAI-compatible configs |
-| Vibe Kanban | YAML | BloopAI task automation |
-| OpenClaw | YAML | Open-source agent runtime |
-| Generic | JSON | Custom integrations |
-
-## Tech Stack
-
-- **Frontend**: React 18 + TypeScript + Vite
-- **Styling**: Tailwind CSS + custom design system
-- **State**: Zustand (9 stores with persist middleware)
-- **Backend**: Express + TypeScript (LLM proxy, MCP manager, team runner)
-- **Agent SDK**: @anthropic-ai/claude-agent-sdk
-- **Testing**: Vitest (unit) + Playwright (E2E) — 646 tests
-- **Fonts**: Geist Sans (body) + Geist Mono (labels)
-
-## Documentation
-
-| Document | Description |
-|---|---|
-| [Release Notes v0.2.0](docs/RELEASE-v0.2.0.md) | What's new in v0.2.0 |
-| [Usage Guide](docs/USAGE-GUIDE.md) | Comprehensive usage guide |
-| [Hurricane Use Case](docs/USE-CASE-HURRICANE.md) | End-to-end maritime hurricane response validation |
-| [Dogfood Review](docs/DOGFOOD-REVIEW.md) | Can Modular Studio improve itself? |
-| [Agent Architecture](docs/AGENT-ARCHITECTURE.md) | Platform design and agent definition format |
-| [Context Engineering Vision](docs/CONTEXT-ENGINEERING-VISION.md) | Product vision and value proposition |
-| [Knowledge Pipeline v2](docs/KNOWLEDGE-PIPELINE-V2.md) | Pipeline architecture spec |
-| [Memory System](docs/MEMORY-SYSTEM-ANALYSIS.md) | Memory management design |
-
-## Contributing
-
-We use conventional commits:
-
-```
-feat: add embedding-based navigation
-fix: budget allocator overflow on empty sources
-docs: add hurricane use case validation
-refactor: simplify depth filter to budget multiplier
-test: add contradiction detector edge cases
-```
-
-### Development workflow
-
-1. Fork and clone the repository
-2. `npm install --legacy-peer-deps`
-3. `npm run dev` — starts frontend + backend
-4. Make changes, write tests
-5. `npm test` — ensure all tests pass
-6. `npx tsc --noEmit` — verify TypeScript compiles
-7. Submit a PR with conventional commit title
-
-### Code quality
-
-- No dead code — if it's not used, delete it
-- DRY + KISS — prefer simplicity over abstraction
-- Continuous refactoring — leave code better than you found it
-- Squash-and-merge for PRs
-
-## Acknowledgments
-
-- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) — Rust Token Killer. Our context compression module is inspired by RTK's approach to minimizing LLM token consumption.
-- [ReactFlow](https://reactflow.dev) — Used for the visual canvas mode.
-- [Anthropic](https://anthropic.com) — Claude Agent SDK for backend agent execution.
-
-## License
-
-Apache License 2.0 — see [LICENSE](LICENSE) for details.
-
----
-
-*Context engineering is the layer every AI platform needs. Modular Studio is that layer.*
+# Modular Studio
+
+**The context engineering IDE for AI agents**
+
+Build knowledge pipelines, not just prompts. Design AI systems that understand your codebase through tree-aware retrieval and deep contextual intelligence.
+
+## Quick Start
+
+```bash
+npx modular-studio
+```
+
+Open [localhost:4800](http://localhost:4800) and start building.
+
+## Key Features
+
+- **🌳 Tree-Aware Retrieval** — Semantic search that understands code structure
+- **🔌 150+ MCP Connectors** — Integrate with any system or service
+- **⚡ Built-in Tools** — GitHub indexing, file management, embeddings out of the box
+- **📊 Pipeline Visibility** — See exactly how context flows through your system
+- **🤖 Multi-Agent** — Coordinate multiple AI agents with shared knowledge
+- **📤 Export Anywhere** — Generate prompts for Claude, ChatGPT, or any LLM
+
+## How It Compares
+
+| | **Traditional RAG** | **Prompt Engineering** | **Modular Studio** |
+|---|---|---|---|
+| **Context Quality** | Document chunks | Manual examples | Tree-aware semantic |
+| **Knowledge Integration** | Static embeddings | Copy-paste | Live repository sync |
+| **Collaboration** | Team wikis | Shared prompts | Version-controlled pipelines |
+| **Debugging** | Black box | Trial and error | Visual pipeline inspection |
+| **Scalability** | Database scaling | Prompt size limits | Distributed knowledge graphs |
+
+## Requirements
+
+- **Node 18+** 
+- **API Key** (Anthropic, OpenAI, or compatible)
+
+## License
+
+Apache 2.0 — Free for commercial and open source use.

package/dist/assets/{graphPopulator-C6jg83nL.js → graphPopulator-CKGQeaUP.js}

@@ -1 +1 @@
-import{u as l}from"./index-CXhIX28x.js";function c(o,n){const t=[],a=[];t.push({name:o,entityType:"repository",observations:[`Tech stack: ${n.stack.join(", ")}`,`Total files: ${n.totalFiles}`,`Total tokens: ${n.totalTokens}`,...(n.conventions??[]).map(e=>`Convention: ${e}`)]});for(const e of n.features){const s=`${o}/${e.name}`;t.push({name:s,entityType:"feature",observations:[`Key files: ${e.keyFiles.join(", ")}`,...(e.stores??[]).map(i=>`Store: ${i}`),...(e.routes??[]).map(i=>`Route: ${i}`),...e.componentCount?[`Components: ${e.componentCount}`]:[]]}),a.push({from:o,to:s,relationType:"has_feature"});for(const i of e.keyFiles.slice(0,5)){const r=`${o}:${i}`;t.push({name:r,entityType:"file",observations:[`Path: ${i}`,`Feature: ${e.name}`]}),a.push({from:s,to:r,relationType:"contains_file"})}}for(const e of n.modules??[]){const s=`${o}/module:${e.name}`;t.push({name:s,entityType:"module",observations:[`Files: ${e.files.length}`,`Key files: ${e.files.slice(0,5).join(", ")}`]}),a.push({from:o,to:s,relationType:"has_module"})}return{entities:t,relations:a}}async function f(o,n){const t=l.getState(),a=t.servers.find(i=>i.status==="connected"&&i.tools.some(r=>r.name==="create_entities"));if(!a)return;const{entities:e,relations:s}=c(o,n);try{e.length>0&&await t.callTool(a.id,"create_entities",{entities:e}),s.length>0&&await t.callTool(a.id,"create_relations",{relations:s})}catch{}}async function m(o){for(const{name:n,scan:t}of o)await f(n,t)}export{m as populateGraphFromMultiScan,f as populateGraphFromScan};
+import{u as l}from"./index-DD78gpRw.js";function c(o,n){const t=[],a=[];t.push({name:o,entityType:"repository",observations:[`Tech stack: ${n.stack.join(", ")}`,`Total files: ${n.totalFiles}`,`Total tokens: ${n.totalTokens}`,...(n.conventions??[]).map(e=>`Convention: ${e}`)]});for(const e of n.features){const s=`${o}/${e.name}`;t.push({name:s,entityType:"feature",observations:[`Key files: ${e.keyFiles.join(", ")}`,...(e.stores??[]).map(i=>`Store: ${i}`),...(e.routes??[]).map(i=>`Route: ${i}`),...e.componentCount?[`Components: ${e.componentCount}`]:[]]}),a.push({from:o,to:s,relationType:"has_feature"});for(const i of e.keyFiles.slice(0,5)){const r=`${o}:${i}`;t.push({name:r,entityType:"file",observations:[`Path: ${i}`,`Feature: ${e.name}`]}),a.push({from:s,to:r,relationType:"contains_file"})}}for(const e of n.modules??[]){const s=`${o}/module:${e.name}`;t.push({name:s,entityType:"module",observations:[`Files: ${e.files.length}`,`Key files: ${e.files.slice(0,5).join(", ")}`]}),a.push({from:o,to:s,relationType:"has_module"})}return{entities:t,relations:a}}async function f(o,n){const t=l.getState(),a=t.servers.find(i=>i.status==="connected"&&i.tools.some(r=>r.name==="create_entities"));if(!a)return;const{entities:e,relations:s}=c(o,n);try{e.length>0&&await t.callTool(a.id,"create_entities",{entities:e}),s.length>0&&await t.callTool(a.id,"create_relations",{relations:s})}catch{}}async function m(o){for(const{name:n,scan:t}of o)await f(n,t)}export{m as populateGraphFromMultiScan,f as populateGraphFromScan};