{"id":45845522,"url":"https://github.com/pleaseai/soop","last_synced_at":"2026-05-28T01:05:02.285Z","repository":{"id":336876510,"uuid":"1149001416","full_name":"pleaseai/soop","owner":"pleaseai","description":"Can't see the forest for the trees.","archived":false,"fork":false,"pushed_at":"2026-03-28T15:45:06.000Z","size":33044,"stargazers_count":1,"open_issues_count":24,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T17:45:52.302Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.cubic.dev/wiki/pleaseai/soop","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pleaseai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-03T16:01:22.000Z","updated_at":"2026-03-28T15:45:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pleaseai/soop","commit_stats":null,"previous_names":["pleaseai/rpg","pleaseai/soop"],"tags_count":98,"template":false,"template_full_name":null,"purl":"pkg:github/pleaseai/soop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fsoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fsoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fsoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fsoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pleaseai","download_url":"https://codeload.github.com/pleaseai/soop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pleaseai%2Fsoop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-27T01:33:14.404Z","updated_at":"2026-05-28T01:05:02.279Z","avatar_url":"https://github.com/pleaseai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# soop please: Repository Planning Graph\n\nA unified framework for repository understanding and generation based on the Repository Planning Graph (RPG) representation.\n\n[![codecov](https://codecov.io/gh/pleaseai/soop/graph/badge.svg?token=PfprF4qUBw)](https://codecov.io/gh/pleaseai/soop)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_soop\u0026metric=alert_status\u0026token=689e64c38ea80939aaaa4089f723cfc1f879d9c1)](https://sonarcloud.io/summary/new_code?id=pleaseai_soop)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_soop\u0026metric=security_rating\u0026token=689e64c38ea80939aaaa4089f723cfc1f879d9c1)](https://sonarcloud.io/summary/new_code?id=pleaseai_soop)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_soop\u0026metric=vulnerabilities\u0026token=689e64c38ea80939aaaa4089f723cfc1f879d9c1)](https://sonarcloud.io/summary/new_code?id=pleaseai_soop)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=pleaseai_soop\u0026metric=bugs\u0026token=689e64c38ea80939aaaa4089f723cfc1f879d9c1)](https://sonarcloud.io/summary/new_code?id=pleaseai_soop)\n\n## Overview\n\nThis project implements the concepts from two research papers:\n\n1. **RPG-ZeroRepo** ([arXiv:2509.16198](https://arxiv.org/abs/2509.16198)) - Repository generation from scratch using structured planning graphs\n2. **RPG-Encoder** ([arXiv:2602.02084](https://arxiv.org/abs/2602.02084)) - Encoding existing repositories into RPG for understanding and navigation\n\n### Key Insight\n\nRepository comprehension and generation are inverse processes within a unified reasoning cycle:\n- **Generation**: Expands intent into implementation (Intent → Code)\n- **Comprehension**: Compresses implementation back into intent (Code → Intent)\n\nRPG serves as a **unified intermediate representation** that bridges both directions.\n\n## Architecture\n\n### Repository Planning Graph (RPG) Structure\n\nRPG is a hierarchical, dual-view graph `G = (V, E)`:\n\n```\n                    ┌─────────────────────────────────────────┐\n                    │           Repository Planning Graph      │\n                    └─────────────────────────────────────────┘\n                                        │\n                    ┌───────────────────┴───────────────────┐\n                    │                                       │\n              ┌─────▼─────┐                         ┌───────▼──────┐\n              │  Nodes (V) │                         │  Edges (E)   │\n              └─────┬─────┘                         └───────┬──────┘\n                    │                                       │\n        ┌───────────┴───────────┐               ┌───────────┴───────────┐\n        │                       │               │                       │\n  ┌─────▼─────┐          ┌──────▼─────┐   ┌─────▼─────┐          ┌──────▼─────┐\n  │ High-level │          │ Low-level  │   │ Functional │          │ Dependency │\n  │   Nodes    │          │   Nodes    │   │   Edges    │          │   Edges    │\n  │  (V_H)     │          │   (V_L)    │   │ (E_feature)│          │  (E_dep)   │\n  └────────────┘          └────────────┘   └────────────┘          └────────────┘\n        │                       │                 │                       │\n  Architectural           Atomic            Teleological            Logical\n  directories          implementations        hierarchy           interactions\n                      (files, classes,                           (imports, calls)\n                       functions)\n```\n\n### Node Structure\n\nEach node `v = (f, m)` contains:\n- **f (Semantic Feature)**: Describes functionality (e.g., \"handles authentication\")\n- **m (Structural Metadata)**: Code entity attributes (type, path, etc.)\n\n### Dual-View Edges\n\n1. **Functional Edges (E_feature)**: Parent-child relationships establishing feature hierarchy\n2. **Dependency Edges (E_dep)**: Import/call relationships mapping execution logic\n\n## Components\n\n### 1. RPG-ZeroRepo: Repository Generation\n\nGenerate repositories from high-level specifications through three stages:\n\n| Stage | Description |\n|-------|-------------|\n| **A. Proposal-Level** | Feature Tree → Explore-Exploit Selection → Goal-Aligned Refactoring |\n| **B. Implementation-Level** | File Structure → Data Flow → Interface Design |\n| **C. Code Generation** | Topological Traversal → TDD → Validation Pipeline |\n\n### 2. RPG-Encoder: Repository Understanding\n\nExtract RPG from existing codebases through three mechanisms:\n\n| Mechanism | Description |\n|-----------|-------------|\n| **Encoding** | Semantic Lifting → Structural Reorganization → Artifact Grounding |\n| **Evolution** | Commit-Level Incremental Updates (Add/Modify/Delete) |\n| **Operation** | SearchNode, FetchNode, ExploreRPG Tools |\n\n## Installation\n\n```bash\n# Install Bun (if not installed)\ncurl -fsSL https://bun.sh/install | bash\n\n# Clone and install\ngit clone https://github.com/pleaseai/soop.git\ncd soop\nbun install\n```\n\n## Quick Start\n\n### Repository Generation (ZeroRepo)\n\n```typescript\nimport { ZeroRepo } from '@pleaseai/soop'\n\n// Initialize with repository specification\nconst zerorepo = new ZeroRepo({\n  spec: `A machine learning library with data preprocessing,\n         algorithms (regression, classification, clustering),\n         and evaluation metrics.`\n})\n\n// Stage A: Build functionality graph\nconst funcGraph = await zerorepo.buildProposalGraph()\n\n// Stage B: Add implementation details\nconst rpg = await zerorepo.buildImplementationGraph(funcGraph)\n\n// Stage C: Generate code\nawait zerorepo.generateRepository(rpg, './generated_repo')\n```\n\n### Repository Understanding (Encoder)\n\n```typescript\nimport { RPGEncoder, SearchNode, FetchNode, ExploreRPG } from '@pleaseai/soop'\n\n// Encode existing repository\nconst encoder = new RPGEncoder('./my_project')\nconst rpg = await encoder.encode()\n\n// Use agentic tools for navigation\nconst search = new SearchNode(rpg)\nconst results = await search.query({\n  mode: 'features',\n  featureTerms: ['handle authentication', 'validate token']\n})\n\n// Fetch detailed information\nconst fetch = new FetchNode(rpg)\nconst details = await fetch.get({\n  codeEntities: ['auth/login.ts:LoginHandler']\n})\n\n// Explore dependencies\nconst explore = new ExploreRPG(rpg)\nconst deps = await explore.traverse({\n  startNode: 'auth/login.ts:LoginHandler',\n  edgeType: 'dependency'\n})\n```\n\n### Incremental Updates\n\n```typescript\n// Update RPG with new commits\nawait encoder.evolve({ commitRange: 'HEAD~5..HEAD' })\n```\n\n### CLI Usage\n\n```bash\n# Encode a repository\nsoop encode ./my_project -o repo.json\n\n# Encode with a specific LLM provider/model\nsoop encode ./my_project -m google                    # Google Gemini (default model)\nsoop encode ./my_project -m openai/gpt-5.2            # OpenAI with specific model\nsoop encode ./my_project -m anthropic/claude-haiku-4.5 # Anthropic Haiku\nsoop encode ./my_project -m claude-code/haiku          # Claude Code (no API key needed)\nsoop encode ./my_project --no-llm                      # Heuristic only (no LLM)\n\n# Generate from specification\nsoop generate --spec \"A REST API for user management\" -o ./output\n\n# Search in RPG\nsoop search --graph graph.json --term \"authentication\"\n\n# Evolve with commits (also supports -m/--model)\nsoop evolve --graph graph.json --commits HEAD~5..HEAD\nsoop evolve --graph graph.json -m google --commits HEAD~5..HEAD\n```\n\n#### Model Configuration\n\nThe `-m, --model` option uses `provider/model` format. If the model is omitted, a default is used.\n\n| Provider | Format | Default Model | API Key Env Var |\n|----------|--------|---------------|-----------------|\n| `openai` | `openai/gpt-5.2` | `gpt-4o` | `OPENAI_API_KEY` |\n| `anthropic` | `anthropic/claude-haiku-4.5` | `claude-sonnet-4.5` | `ANTHROPIC_API_KEY` |\n| `google` | `google/gemini-3-pro-preview` | `gemini-3.1-flash-lite-preview` | `GOOGLE_GENERATIVE_AI_API_KEY` |\n| `claude-code` | `claude-code/haiku` | `sonnet` | Not required (uses subscription) |\n\n## Project Structure\n\n```\nsoop/                              # Private monorepo root (not published)\n├── packages/\n│   ├── soop/                      # Published package: @pleaseai/soop\n│   │   ├── src/index.ts           # Main exports (re-exports all workspace packages)\n│   │   ├── bin/soop               # CLI binary\n│   │   ├── bin/soop-mcp           # MCP server shim (deprecated, use `soop mcp`)\n│   │   └── package.json\n│   │\n│   ├── ast/      # @pleaseai/soop-ast     — tree-sitter parser (multi-language, native via namu)\n│   ├── utils/    # @pleaseai/soop-utils   — LLM, git helpers, logger\n│   ├── store/    # @pleaseai/soop-store   — Storage interfaces \u0026 implementations\n│   ├── graph/    # @pleaseai/soop-graph   — RPG data structures\n│   ├── encoder/  # @pleaseai/soop-encoder — Code → RPG extraction\n│   ├── tools/    # @pleaseai/soop-tools   — Agentic navigation tools\n│   ├── zerorepo/ # @pleaseai/soop-zerorepo — Intent → Code generation\n│   ├── namu/     # @pleaseai/soop-namu   — native tree-sitter backend + NamuNode adapter\n│   ├── mcp/      # @pleaseai/soop-mcp    — MCP server\n│   ├── cli/      # @pleaseai/soop-cli    — CLI entry point\n│   └── soop-native/ # @pleaseai/soop-native — native binary distribution (bun compiled)\n│\n├── tests/\n│   └── fixtures/                  # Shared test fixtures (sample-rpg.json, superjson)\n├── docs/\n├── scripts/\n├── package.json                   # Monorepo root (private, version 0.0.0)\n└── README.md\n```\n\n## Benchmarks\n\n### Repository Understanding (SWE-bench)\n\n| Method | SWE-bench Verified (Acc@5) | SWE-bench Live Lite |\n|--------|---------------------------|---------------------|\n| API Documentation | 82.1% | - |\n| Dependency Graph | 79.3% | - |\n| **RPG-Encoder** | **93.7%** | **+10%** over best baseline |\n\n### Repository Generation (RepoCraft)\n\n| Method | Code Lines | Coverage | Test Accuracy |\n|--------|-----------|----------|---------------|\n| Claude Code | ~9.2K | 54.2% | 33.9% |\n| Other Baselines | ~530 | ~15% | ~10% |\n| **ZeroRepo** | **~36K** | **81.5%** | **69.7%** |\n\n## Requirements\n\n- Bun 1.0+\n- LLM provider access (choose one):\n  - OpenAI, Anthropic, or Google API key (for API-based providers)\n  - Claude Desktop with Pro/Max subscription (for Claude Code provider, no API key needed)\n\n## Citation\n\n```bibtex\n@article{luo2025rpg,\n  title={RPG: A Repository Planning Graph for Unified and Scalable Codebase Generation},\n  author={Luo, Jane and Zhang, Xin and Liu, Steven and Wu, Jie and others},\n  journal={arXiv preprint arXiv:2509.16198},\n  year={2025}\n}\n\n@article{luo2025rpgencoder,\n  title={Closing the Loop: Universal Repository Representation with RPG-Encoder},\n  author={Luo, Jane and Yin, Chengyu and Zhang, Xin and others},\n  journal={arXiv preprint arXiv:2602.02084},\n  year={2025}\n}\n```\n\n## License\n\nMIT License\n\n## Documentation\n\n- [Implementation Status](docs/implementation-status.md) — Paper vs implementation gap analysis (implemented / not implemented / needs modification)\n- [RPG Operation](docs/rpg-operation.md) — SearchNode, FetchNode, ExploreRPG tools reference and canonical orchestration patterns\n- [Vendor Comparison](docs/vendor-comparison.md) — Microsoft Python reference vs TypeScript implementation technical differences\n\n## Related Projects\n\n- [RepoGraph](https://github.com/ozyyshr/RepoGraph) ([arXiv:2410.14684](https://arxiv.org/abs/2410.14684)) — Repository-level code graph module for AI software engineering (ICLR 2025); constructs dependency and reference graphs to provide LLMs with repository-wide navigation context, achieving state-of-the-art on SWE-bench among open-source frameworks\n- [Beads](https://github.com/steveyegge/beads) — Distributed, git-backed task tracking system for AI coding agents; provides persistent structured memory and dependency-aware task graphs for long-horizon agent workflows\n\n## Acknowledgments\n\nThis implementation is based on research from Microsoft Research Asia.\n\n- [RPG-ZeroRepo Paper](https://arxiv.org/abs/2509.16198)\n- [RPG-Encoder Paper](https://arxiv.org/abs/2602.02084)\n- [Project Page](https://ayanami2003.github.io/RPG-Encoder/)\n- [Original Code](https://github.com/microsoft/RPG-ZeroRepo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpleaseai%2Fsoop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpleaseai%2Fsoop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpleaseai%2Fsoop/lists"}