|
Download docs/3.0/ploy3.0.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 25.7 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/3.0/ploy3.0.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/3.0/ploy3.0.md
-
curl -L -o ploy3.0.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/3.0/ploy3.0.md
25.7 kB
| # Polyhedra PRD v3.0 | |
| ## Collaborative Multi-Agent Research Team | |
| ```yaml | |
| project_name: Polyhedra | |
| version: 3.0.0 | |
| type: Multi-Agent System + Messaging Integration | |
| status: Draft | |
| created: 2026-03-12 | |
| updated: 2026-03-12 | |
| changelog: | |
| v3.0.0: | |
| - New paradigm: single-agent CLI β collaborative multi-agent research team | |
| - New interface: Slack / Teams / Spark thread as primary collaboration surface | |
| - New model: agents post as users, @mention each other natively | |
| - New feature: fluid human role-switching (observer β participant β role owner) | |
| - New layer: shared research state + thread history as persistent context | |
| - Retained: CLI (poly commands), MCP server (IDE integrations), human-in-the-loop checkpoints, artifact-first outputs | |
| - Clarified: CLI, MCP, and messaging thread are three entry points into the same agent system | |
| v2.x: | |
| - See legacy PRD for v1.0βv1.2 history (CLI, MCP server, IDE integrations) | |
| ``` | |
| --- | |
| ## 1. Product Vision | |
| Polyhedra v3.0 transforms the research assistant from a single tool into a **collaborative research team that lives inside your existing messaging workspace**. | |
| Each agent joins a thread as a named participant. They @mention each other like human teammates. The user picks which roles to include, can step into any role themselves at any time, and can hand that role back. The thread history is the research record. | |
| **Design philosophy (unchanged from v2.x):** | |
| The goal is not to automate research β it is to handle the tedious so humans retain creative ownership. Agents do the searching, synthesising, challenging, and drafting. Humans decide the direction, approve the pivots, and own the ideas. | |
| **What changes in v3.0:** | |
| The collaboration medium is no longer a CLI or a chat window. It is a Slack/Teams/Spark channel β a space researchers already use daily. This eliminates the tool-switching cost and makes the research process naturally auditable and shareable. | |
| --- | |
| ## 2. Target Users | |
| The primary user is a **solo researcher** who wants an AI research team they can direct, observe, and participate in at will. This maps to the largest unserved segment in the current market: individual academics, PhD students, and independent researchers who need the leverage of a team but don't have one. | |
| Secondary users include small research groups where human members and AI agents coexist in the same thread. | |
| **User needs (ranked by market demand):** | |
| 1. Literature discovery and synthesis β the most time-consuming step, most requested capability | |
| 2. Research gap identification β knowing where to contribute | |
| 3. Hypothesis and methodology design β moving from field knowledge to a research plan | |
| 4. Critical review β catching weak arguments before submission | |
| 5. Academic writing and citation management β drafting and polishing | |
| --- | |
| ## 3. Core Concepts | |
| ### 3.1 The Thread Model | |
| A Polyhedra session is a messaging thread. Agents are workspace members. The user creates a thread, selects which agent roles to activate, and the team assembles. | |
| Every agent has a workspace identity: a name, a role title, and a profile that describes their responsibilities. When @mentioned, they respond in the thread. When they need another agent's input, they @mention them. The thread becomes a readable log of the research process. | |
| ### 3.2 Agent Roles | |
| **Core agents** (available at session init, user selects which to include): | |
| | Agent | Role | Responsibilities | | |
| |-------|------|-----------------| | |
| | Scout | Literature Researcher | Searches Semantic Scholar / ArXiv, screens papers, produces structured literature summaries | | |
| | Strategist | Research Designer | Identifies gaps in the literature, frames hypotheses, proposes methodology | | |
| | Critic | Devil's Advocate | Challenges claims made by other agents, flags weak baselines, stress-tests arguments | | |
| | Scribe | Writer / Editor | Drafts paper sections, maintains narrative coherence, manages BibTeX citations | | |
| | Coordinator | Project Manager | Orchestrates the team, routes tasks from @mentions, manages checkpoints, tracks research state | | |
| **Specialist agents** (on-demand, added mid-session if needed): | |
| | Agent | Role | Responsibilities | | |
| |-------|------|-----------------| | |
| | Analyst | Data Interpreter | Interprets experiment results, runs statistical checks, generates charts | | |
| | Reviewer | Submission Preparer | Final review pass for venue-specific requirements, formatting, and completeness | | |
| ### 3.3 Human Role Fluidity | |
| The user is not a passive observer. At any moment they can: | |
| - **Observe** β read the thread without posting | |
| - **Participate** β @mention agents, ask questions, redirect the work | |
| - **Replace a role** β declare themselves the Critic for a section, write their own critique, then hand the role back. The agent resumes from where the human left off, reading the thread to catch up. | |
| - **Build the team** β at init, choose which roles to include and whether any are human-held from the start | |
| Role switches are explicit, declared in the thread: `I'm taking over as Critic for this section.` or `/poly role critic human`. Agents monitor the thread for these signals. | |
| ### 3.4 Shared Research State | |
| Every agent reads from and writes to a structured document called the **Research State**. This is a compressed, always-current summary of: | |
| - The research goal and current framing | |
| - Key papers and their relevance | |
| - Identified gaps and active hypotheses | |
| - Decisions made and their rationale | |
| - Outstanding questions | |
| This solves the context window problem: agents read the Research State (compact) rather than the full thread (unbounded). The Coordinator is responsible for keeping it updated after each significant thread event. | |
| ### 3.5 Human Checkpoints | |
| At defined moments, the Coordinator pauses autonomous agent activity and posts a checkpoint summary to the thread. The user must respond before agents continue. | |
| Default checkpoint triggers: | |
| - After Scout completes a literature search (before Strategist proceeds) | |
| - After Strategist proposes research directions (before any drafting begins) | |
| - Before Scribe starts writing a new paper section | |
| - When any agent flags a low-confidence output | |
| - When estimated LLM cost for the next operation exceeds a configurable threshold | |
| Checkpoint format (posted by Coordinator): | |
| ``` | |
| βΈ Checkpoint: Literature Review Complete | |
| Scout found 34 papers. Key findings: | |
| β’ 3 dominant approaches identified (transformer-based, graph-based, hybrid) | |
| β’ Gap: no work combining sparse attention with dynamic routing | |
| β’ 8 papers flagged as must-reads | |
| Next step: Strategist will propose 3 research directions based on this. | |
| Proceed? [yes / adjust / stop] | |
| ``` | |
| --- | |
| ## 4. Functional Requirements | |
| ### FR-001: Session Initialization | |
| The user creates a thread and invokes `/poly init`. A role picker is displayed. The user selects which agents to activate. Each selected agent joins the thread as a workspace member. The Coordinator always joins β it cannot be deselected. | |
| Roles not selected are inactive but can be added mid-session with `/poly add [role]`. | |
| ### FR-002: Agent @mention Protocol | |
| Any participant (human or agent) can @mention an agent by name. The Coordinator intercepts all @mentions and routes them to the appropriate agent. The mentioned agent reads the thread context, executes its task, and posts a response in the thread. | |
| Agents may @mention other agents. The Coordinator tracks active @mention chains to prevent loops (max depth: 3). | |
| ### FR-003: Human Role Takeover | |
| The user can take over any agent role with `/poly role [name] human`. The agent becomes dormant. Subsequent @mentions of that role name are directed to the user. The user can reinstate the agent with `/poly role [name] agent`. The agent reads the thread from the point of takeover and resumes. | |
| ### FR-004: Research State Management | |
| The Coordinator maintains the Research State document. It is updated automatically after each checkpoint. Agents may request a Research State update mid-task if a significant discovery is made. The Research State is pinned in the thread and accessible via `/poly state`. | |
| ### FR-005: Human Checkpoint Gate | |
| The Coordinator halts agent activity at checkpoint triggers (see Β§3.5). No agent posts to the thread until the user responds. Timeout after 24 hours defaults to "stop" to prevent runaway tasks. | |
| ### FR-006: Scout β Literature Search | |
| Scout accepts a research question or topic as input. It queries Semantic Scholar and ArXiv, screens results for relevance, deduplicates, and produces a structured summary. Output format: a markdown table of papers with columns for title, year, relevance score, and a one-sentence summary. Maximum 50 papers per search. Scout @mentions Strategist when complete. | |
| ### FR-007: Strategist β Gap Analysis and Hypothesis Generation | |
| Strategist reads the Scout output and the Research State. It produces up to 3 research directions, each with: a framing of the gap, a hypothesis, a proposed methodology sketch, and a confidence rating. It @mentions Critic to review before posting to the thread. | |
| ### FR-008: Critic β Review and Challenge | |
| Critic reviews outputs from any agent when @mentioned. It produces a structured critique: what is strong, what is weak, what is missing, and what would make this publishable. It does not rewrite β it challenges. The reviewed agent is responsible for revision. | |
| ### FR-009: Scribe β Drafting and Citation Management | |
| Scribe writes paper sections when @mentioned with a section name and relevant context. It reads the Research State for framing and the Scout output for citations. All citations are generated in BibTeX and appended to a running `.bib` file. Scribe @mentions Critic for a review pass before marking a section complete. | |
| ### FR-010: Coordinator β Orchestration | |
| The Coordinator is always active. Responsibilities: | |
| - Parse all @mentions and route tasks | |
| - Track which roles are human vs. agent at any moment | |
| - Maintain and update the Research State | |
| - Trigger and manage checkpoints | |
| - Detect and break @mention loops | |
| - Post cost estimates before high-token operations | |
| - Log all agent actions with timestamps | |
| ### FR-011: Analyst β Data Interpretation (on demand) | |
| When added to a session, Analyst accepts experiment results (CSV, JSON, or pasted data), interprets them, produces summary statistics, identifies trends, and generates a findings narrative suitable for inclusion in a paper results section. | |
| ### FR-012: Artifact Export | |
| At any point, `/poly export` produces a zip containing: the Research State document, all drafted paper sections as markdown files, the `.bib` file, and a full thread log in markdown format. | |
| ### FR-013: Multi-Platform Support | |
| All functionality must work in Slack, Microsoft Teams, and Apache Spark (now Webex). Platform-specific features (e.g. Slack Block Kit for checkpoint UI) are enhancements, not requirements. | |
| --- | |
| ## 5. Non-Functional Requirements | |
| **Latency:** Agent responses must begin streaming within 5 seconds of an @mention. Full responses should complete within 30 seconds for standard tasks. Literature searches may take up to 90 seconds. | |
| **Cost transparency:** Before any operation estimated to cost more than $0.50 in LLM tokens, the Coordinator posts a cost estimate and waits for confirmation. | |
| **Context integrity:** The Research State must never exceed 4,000 tokens to remain readable across all supported LLM contexts. The Coordinator is responsible for compression when approaching this limit. | |
| **Reliability:** If an agent call fails, the Coordinator retries with exponential backoff (max 3 attempts, starting at 2s). If all retries fail, it posts a failure notice in the thread and marks the task as pending. | |
| **Privacy:** Thread content and Research State are not stored beyond the session unless the user explicitly exports. No data is used for model training. | |
| --- | |
| ## 6. Technical Architecture | |
| ### 6.1 Entry Points | |
| Polyhedra has three entry points. They are not competing interfaces β they are different surfaces into the same agent system. The Coordinator and agent pool do not know or care which entry point a task came from. | |
| ``` | |
| βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ | |
| β CLI (poly) β β MCP Server β β Slack / Teams β | |
| β β β β β / Spark thread β | |
| β poly init β β IDE-native β β @mention-driven β | |
| β poly search β β tool calls from β β team session β | |
| β poly export β β Cursor, VS Code β β human + agents β | |
| β local file ops β β GitHub Copilot β β as participants β | |
| β scripting / CI β β Windsurf β β β | |
| ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ | |
| β β β | |
| ββββββββββββββββββββββΌβββββββββββββββββββββ | |
| β unified task interface | |
| βββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββ | |
| β Coordinator Service β | |
| β @mention parser Β· role registry Β· checkpoint engine β | |
| β state manager Β· cost estimator Β· loop detector β | |
| ββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββ | |
| β dispatches tasks | |
| ββββββββββββββββββΌβββββββββββββββββ | |
| βΌ βΌ βΌ | |
| βββββββββββββββ βββββββββββββββ βββββββββββββββ | |
| β Scout β β Strategist β β Critic β | |
| β Scribe β β Analyst β β Reviewer β | |
| ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ | |
| ββββββββββββββββββΌβββββββββββββββββ | |
| β | |
| ββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββ | |
| β Services Layer β | |
| β LLM Router (Claude / GPT / local) β | |
| β Paper Search (Semantic Scholar / ArXiv) β | |
| β Research State store Β· Artifact manager β | |
| βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| ``` | |
| **Entry point comparison:** | |
| | Capability | CLI | MCP Server | Slack/Teams | | |
| |---|---|---|---| | |
| | Full team session | β | β | β | | |
| | Single agent invocation | β | β | β | | |
| | Human role switching | β | β | β | | |
| | Local file access | β | β | β | | |
| | IDE inline responses | β | β | β | | |
| | Shared thread history | β | β | β | | |
| | Scripting / CI automation | β | β | β | | |
| | Checkpoint UI | terminal prompt | IDE dialog | Block Kit / Adaptive Card | | |
| | Research State access | `/poly state` | tool call | pinned message | | |
| | Artifact export | `/poly export` | tool call | `/poly export` | | |
| **Shared state across entry points:** The Research State and artifacts are session-scoped, not interface-scoped. A session started in Slack can be continued via CLI (`poly resume [session-id]`) for local file operations, then returned to Slack. The Research State stays consistent across all entry points. | |
| ### 6.2 Agent Base Class | |
| Every agent shares a common interface: | |
| ```python | |
| class Agent: | |
| name: str | |
| role: str | |
| system_prompt: str # Role definition + behavior rules | |
| async def handle( | |
| self, | |
| mention: Mention, # Who mentioned this agent and what they said | |
| thread_context: list, # Recent thread messages (capped at last N) | |
| research_state: dict, # Current Research State document | |
| ) -> AgentResponse: | |
| ... | |
| async def can_handle(self, mention: Mention) -> bool: | |
| ... | |
| ``` | |
| ### 6.3 Research State Schema | |
| ```yaml | |
| research_state: | |
| goal: str # One-sentence research goal | |
| field: str # Domain / venue target | |
| gaps: list[Gap] # Identified research gaps | |
| active_hypothesis: Hypothesis # Current working hypothesis | |
| key_papers: list[Paper] # Up to 20 most relevant papers | |
| decisions: list[Decision] # Timestamped decisions + rationale | |
| open_questions: list[str] # Unresolved items | |
| last_updated: datetime | |
| version: int | |
| ``` | |
| ### 6.4 Role Registry | |
| The Coordinator maintains a role registry for each session: | |
| ```python | |
| role_registry = { | |
| "scout": RoleEntry(agent=ScoutAgent(), held_by="agent"), | |
| "strategist": RoleEntry(agent=StrategistAgent(), held_by="agent"), | |
| "critic": RoleEntry(agent=CriticAgent(), held_by="human"), # human took over | |
| "scribe": RoleEntry(agent=ScribeAgent(), held_by="agent"), | |
| } | |
| ``` | |
| When `held_by = "human"`, @mentions of that role name are forwarded to the user via a DM or thread highlight. When the user hands back, `held_by` reverts to `"agent"` and the agent is re-initialized with the thread context from the point of takeover. | |
| ### 6.5 Tech Stack | |
| ```yaml | |
| backend: | |
| language: Python 3.11+ | |
| framework: FastAPI (webhook receiver) | |
| agent_framework: custom (thin layer over LLM SDK) | |
| llm: anthropic SDK (primary), openai SDK (optional) | |
| paper_search: semanticscholar, arxiv-api | |
| state_store: Redis (session state), SQLite (artifact persistence) | |
| cli: | |
| framework: typer + rich | |
| entry_point: poly | |
| key_commands: | |
| - poly init # start a new session | |
| - poly search # invoke Scout directly | |
| - poly state # print Research State | |
| - poly resume # rejoin an existing session by ID | |
| - poly export # export all artifacts | |
| - poly role # take over or release an agent role | |
| - poly mcp # start the MCP server | |
| mcp_server: | |
| protocol: MCP (Model Context Protocol) | |
| compatible_ides: [Cursor, VS Code, Windsurf, GitHub Copilot] | |
| exposed_tools: | |
| - search_papers # Scout search | |
| - get_research_state # read current state | |
| - generate_review # Critic review of provided text | |
| - draft_section # Scribe section drafting | |
| - add_citation # BibTeX management | |
| messaging_integrations: | |
| slack: slack-bolt | |
| teams: botframework-sdk | |
| spark: webexteamssdk | |
| deployment: | |
| container: Docker | |
| hosting: any (Railway / Fly.io recommended for solo deployment) | |
| config: environment variables only, no secrets in code | |
| ``` | |
| --- | |
| ## 7. User Experience | |
| ### 7.1 Session Initialization Flow | |
| ``` | |
| User: /poly init | |
| Coordinator: Welcome to Polyhedra. Which agents do you want on this project? | |
| [β Scout] [β Strategist] [β Critic] [β Scribe] [ Analyst] | |
| Are you taking any roles yourself? | |
| [ Scout] [ Strategist] [β Critic] [ Scribe] | |
| You're playing Critic. I'll hold the other roles. | |
| Type your research goal to begin. | |
| User: I want to work on efficient transformers for long-context understanding. | |
| Coordinator: Got it. Saving research goal. | |
| @Scout β please search for papers on efficient transformers | |
| and long-context understanding. | |
| ``` | |
| ### 7.2 Typical Mid-Session Exchange | |
| ``` | |
| Scout: Found 41 papers on efficient transformers + long-context. | |
| Top approaches: sparse attention (18 papers), linear attention (12), | |
| hybrid (11). Notable gap: sparse + linear combinations underexplored. | |
| @Strategist β ready for gap analysis. | |
| Strategist: Three directions stand out: | |
| 1. Sparse-linear hybrid attention β high novelty, medium feasibility | |
| 2. Adaptive context window β medium novelty, high feasibility | |
| 3. Retrieval-augmented long context β lower novelty, high feasibility | |
| @[user as Critic] β your assessment? | |
| User: Direction 1 is the only one that hasn't been beaten to death. | |
| But the feasibility estimate is too optimistic β sparse-linear | |
| integration has known training instability issues. | |
| Strategist: Noted. Revising direction 1 to include a training stability | |
| mitigation strategy. @Scout can you find papers specifically on | |
| sparse-linear training instabilities? | |
| ``` | |
| ### 7.3 Checkpoint Example | |
| ``` | |
| Coordinator: βΈ Checkpoint: Ready to begin drafting | |
| Hypothesis locked: Sparse-linear hybrid attention with | |
| gradient norm clipping achieves 40% compute reduction | |
| on sequences >8k tokens with <2% perplexity increase. | |
| Scribe is ready to draft: Introduction, Related Work. | |
| Estimated cost: ~$1.20 | |
| Proceed? [yes / adjust scope / stop] | |
| User: yes | |
| Scribe: Starting Introduction. Will post a draft in ~2 min. | |
| ``` | |
| --- | |
| ## 8. Development Roadmap | |
| ### Phase 1 β Foundation (Weeks 1β4) | |
| Core infrastructure with Slack integration and two agents. | |
| - Coordinator service: @mention parsing, role registry, checkpoint engine | |
| - Research State: schema, CRUD, compression logic | |
| - Scout agent: Semantic Scholar + ArXiv search, paper summary output | |
| - Strategist agent: gap analysis, hypothesis generation | |
| - Slack integration: webhook receiver, message posting, Block Kit checkpoint UI | |
| - `/poly init`, `/poly state`, `/poly export` slash commands | |
| **Exit criteria:** A user can start a Slack thread, initialize a session, have Scout search for papers, and have Strategist propose research directions with a checkpoint gate. | |
| ### Phase 2 β Full Team (Weeks 5β8) | |
| Remaining core agents, human role switching, Teams integration. | |
| - Critic agent: structured review protocol | |
| - Scribe agent: section drafting, BibTeX management | |
| - Human role takeover/reinstate (`/poly role`) | |
| - Agent context handoff on role switch | |
| - Microsoft Teams integration | |
| - Cost estimation before high-token operations | |
| **Exit criteria:** Full team operational in Slack and Teams. Human can take over and return any role mid-session. | |
| ### Phase 3 β Specialist Agents + Robustness (Weeks 9β12) | |
| Analyst and Reviewer agents, error handling, Spark integration. | |
| - Analyst agent: structured data interpretation, findings narrative | |
| - Reviewer agent: venue-specific checklist review | |
| - Retry + circuit-breaker on LLM failures | |
| - Spark (Webex) integration | |
| - Research State compression when approaching token limit | |
| - Artifact export as formatted zip | |
| **Exit criteria:** End-to-end research session from goal to exportable paper draft with full error recovery. | |
| ### Phase 4 β Learning + Polish (Weeks 13β16) | |
| Preference learning, UX refinements, public release prep. | |
| - User preference profiles: learns preferred venues, writing style, verbosity | |
| - Checkpoint frequency tuning based on user behavior | |
| - Polyhedra web dashboard (optional, read-only view of Research State) | |
| - Documentation, onboarding guide, example sessions | |
| - Open-source release on GitHub | |
| --- | |
| ## 9. Open Questions | |
| These are unresolved design decisions to be revisited before Phase 1 begins. | |
| **Agent identity:** Should agents have persistent names and personas (e.g. "Iris" for Scout) to make the thread feel like a real team? Benefit: stronger social presence, easier to reference. Risk: anthropomorphization may mislead users about agent reliability. | |
| **@mention loop depth:** Max depth of 3 is a heuristic. Real research conversations may legitimately go deeper (Scout β Strategist β Critic β Strategist β Scribe). Consider task graphs instead of simple depth limits. | |
| **Parallel vs. sequential agents:** Currently agents work sequentially (Scout finishes, then Strategist starts). Parallel execution (Scout and Strategist working simultaneously on different sub-tasks) would be faster but harder to coordinate and explain in the thread. Revisit in Phase 2. | |
| **Research State ownership:** Currently only the Coordinator updates the Research State. Should agents be able to propose updates that the Coordinator approves? This would catch more signal but increases coordination complexity. | |
| **Multi-human sessions:** A real research group might have multiple humans in the thread alongside agents. The role registry assumes one human per role. Multi-human support is out of scope for v3.0 but should be designed for in Phase 4. | |
| --- | |
| ## 10. Success Metrics | |
| | Metric | Target (6 months post-launch) | | |
| |--------|-------------------------------| | |
| | Sessions reaching paper draft | >40% | | |
| | Checkpoint approval rate (user proceeds vs. stops) | >70% | | |
| | Human role takeover rate per session | >1 (users engage, not just observe) | | |
| | Time from session init to first Scout output | <90 seconds | | |
| | User-reported time saved vs. solo research | >50% | | |
| | Export rate (users completing to artifact export) | >25% | | |