401 lines
9.9 KiB
Markdown
401 lines
9.9 KiB
Markdown
# Software Requirements Specification (SRS)_ Biomimetic Agentic Orchestration Layer
|
|
|
|
**Date:** 2026-04-14
|
|
**Status:** Draft
|
|
**System Name:** `Project Velocity Colony Orchestration Layer`
|
|
|
|
## 1. Introduction
|
|
|
|
### 1.1 Purpose
|
|
|
|
This SRS defines the functional and non-functional requirements for a biomimetic agentic orchestration layer that integrates:
|
|
|
|
- a forked Open Multi Agent runtime as execution kernel
|
|
- Project Velocity Nemoclaw-derived policy and governance concepts
|
|
- Project Velocity root domain systems including Oracle, CRM, Catalyst, and Sentinel
|
|
|
|
### 1.2 Scope
|
|
|
|
The system accepts a high-level goal and coordinates a colony of specialized agents to produce a reviewed, auditable final output or domain writeback.
|
|
|
|
The system is intended to become the orchestration layer for Project Velocity domain workflows.
|
|
|
|
### 1.3 Intended Audience
|
|
|
|
This document is intended for:
|
|
|
|
- product and systems architects
|
|
- backend and orchestration engineers
|
|
- AI infrastructure engineers
|
|
- QA and validation engineers
|
|
- internal operators defining mission classes
|
|
|
|
## 2. References
|
|
|
|
Primary references used for this SRS:
|
|
|
|
- `.Agent Context/Tech/Tools Understanding.md`
|
|
- `.Agent Context/Tech/README-Open Multi-Agent.md`
|
|
- `.Agent Context/Sprint 1/nemoclaw_setup_truth.md`
|
|
- public Open Multi Agent repository `https://github.com/JackChen-me/open-multi-agent`
|
|
- current root Project Velocity code under `backend/oracle`, `backend/services`, `backend/api`, and Sentinel routes
|
|
|
|
## 3. System Overview
|
|
|
|
The system consists of:
|
|
|
|
- mission intake and normalization
|
|
- planner
|
|
- prompt master
|
|
- research subsystem
|
|
- librarian subsystem
|
|
- worker execution layer
|
|
- aggregation and review layer
|
|
- governance and policy layer
|
|
- domain adapters
|
|
|
|
The system must preserve the current Project Velocity ownership boundaries and must not replace the root backend.
|
|
|
|
## 4. Architectural Constraints
|
|
|
|
The system shall use a modular architecture.
|
|
|
|
The system shall not depend on leaked or provenance-unclear upstream code.
|
|
|
|
The system shall support mixed model providers.
|
|
|
|
The system shall keep policy enforcement external to worker prompts wherever possible.
|
|
|
|
The system shall preserve Oracle v1, FastAPI root ownership, and Sentinel ownership.
|
|
|
|
## 5. Functional Requirements
|
|
|
|
### FR-1 Mission Intake
|
|
|
|
The system shall accept a goal payload containing:
|
|
|
|
- source surface
|
|
- user prompt
|
|
- desired output type
|
|
- risk or sensitivity hint when available
|
|
|
|
### FR-2 Mission Normalization
|
|
|
|
The system shall normalize the goal into a canonical mission envelope with:
|
|
|
|
- mission identifier
|
|
- normalized objective
|
|
- risk classification
|
|
- time budget
|
|
- token budget
|
|
- requested outputs
|
|
|
|
### FR-3 Task Planning
|
|
|
|
The system shall decompose the mission into a directed acyclic graph of tasks.
|
|
|
|
Each task shall include:
|
|
|
|
- unique task identifier
|
|
- role type
|
|
- objective
|
|
- dependency list
|
|
- success criteria
|
|
- required capabilities
|
|
|
|
### FR-4 Prompt Package Generation
|
|
|
|
The system shall generate a prompt package per task using:
|
|
|
|
- prompt templates
|
|
- examples where configured
|
|
- task metadata
|
|
- mission constraints
|
|
- tool scope
|
|
|
|
### FR-5 External Research
|
|
|
|
The system shall support a research role capable of:
|
|
|
|
- executing search queries
|
|
- browsing webpages
|
|
- returning evidence packets with citation metadata
|
|
|
|
### FR-6 Internal Retrieval and Routing
|
|
|
|
The system shall support a librarian role capable of:
|
|
|
|
- identifying relevant internal data sources
|
|
- issuing scoped access passes
|
|
- returning cached previews and data pointers
|
|
|
|
### FR-7 Worker Provisioning
|
|
|
|
The system shall spawn worker tasks with:
|
|
|
|
- prompt package
|
|
- task objective
|
|
- tool permissions
|
|
- librarian pass
|
|
- research artifacts when applicable
|
|
|
|
### FR-8 Parallel Execution
|
|
|
|
The system shall execute independent tasks in parallel, subject to concurrency limits and policy constraints.
|
|
|
|
### FR-9 Aggregation
|
|
|
|
The system shall aggregate worker outputs into a structured aggregation packet.
|
|
|
|
### FR-10 Review
|
|
|
|
The system shall execute one bounded review pass over the aggregation packet before final delivery.
|
|
|
|
### FR-11 Final Delivery
|
|
|
|
The system shall deliver a final output packet to:
|
|
|
|
- the originating user-facing surface
|
|
- or a root domain subsystem
|
|
|
|
### FR-12 Governance
|
|
|
|
The system shall evaluate policy constraints before executing:
|
|
|
|
- sensitive tools
|
|
- external network calls
|
|
- filesystem writes where applicable
|
|
- domain writebacks
|
|
|
|
### FR-13 Audit Logging
|
|
|
|
The system shall emit mission-level and task-level audit records for:
|
|
|
|
- planning
|
|
- prompt package selection
|
|
- tool use
|
|
- model use
|
|
- writeback attempts
|
|
- review findings
|
|
|
|
### FR-14 Domain Adapters
|
|
|
|
The system shall expose adapter boundaries for:
|
|
|
|
- Oracle
|
|
- CRM
|
|
- Catalyst
|
|
- Sentinel
|
|
|
|
### FR-15 Artifact Persistence
|
|
|
|
The system shall persist mission and artifact records in a store controlled by Project Velocity rather than relying solely on in-memory framework state.
|
|
|
|
### FR-16 Prompt Registry
|
|
|
|
The system shall maintain a prompt registry with:
|
|
|
|
- prompt template identifiers
|
|
- versioning
|
|
- example sets
|
|
- role associations
|
|
|
|
### FR-17 Quorum and Approval Hooks
|
|
|
|
The system shall support configurable approval paths for high-risk missions, including:
|
|
|
|
- single human approval
|
|
- automatic review approval
|
|
- dual-agent review agreement
|
|
|
|
### FR-18 Failure Handling
|
|
|
|
The system shall handle:
|
|
|
|
- task failure
|
|
- task timeout
|
|
- policy rejection
|
|
- low-confidence evidence
|
|
- partial mission completion
|
|
|
|
and shall still return a structured final mission status.
|
|
|
|
## 6. External Interfaces
|
|
|
|
### 6.1 Mission Intake Interface
|
|
|
|
Recommended interface:
|
|
|
|
- internal HTTP or RPC endpoint from FastAPI to colony runtime
|
|
- JSON mission envelope request and response
|
|
|
|
### 6.2 Domain Adapter Interfaces
|
|
|
|
Each adapter should support:
|
|
|
|
- mission submission
|
|
- progress event subscription
|
|
- artifact retrieval
|
|
- writeback execution or rejection
|
|
|
|
### 6.3 Tool Interface
|
|
|
|
Tools shall expose:
|
|
|
|
- tool identifier
|
|
- input schema
|
|
- policy class
|
|
- timeout behavior
|
|
- result schema
|
|
|
|
### 6.4 Research Interface
|
|
|
|
Research outputs shall include:
|
|
|
|
- source URI
|
|
- title when available
|
|
- snippet
|
|
- summary
|
|
- retrieval timestamp
|
|
- confidence
|
|
|
|
### 6.5 Librarian Interface
|
|
|
|
Librarian passes shall include:
|
|
|
|
- allowed resource families
|
|
- recommended paths or queries
|
|
- cache pointers
|
|
- expiration metadata
|
|
|
|
## 7. Data Model
|
|
|
|
The following persistent entities are required:
|
|
|
|
- `missions`
|
|
- `mission_tasks`
|
|
- `prompt_packages`
|
|
- `research_artifacts`
|
|
- `library_passes`
|
|
- `worker_results`
|
|
- `aggregation_packets`
|
|
- `review_packets`
|
|
- `policy_decisions`
|
|
- `tool_invocations`
|
|
- `pheromone_signals`
|
|
|
|
Each entity shall include:
|
|
|
|
- a primary identifier
|
|
- timestamps
|
|
- provenance metadata
|
|
- mission linkage
|
|
|
|
## 8. Non-Functional Requirements
|
|
|
|
### 8.1 Reliability
|
|
|
|
The system shall degrade gracefully on partial task failure and shall produce a final mission state instead of hanging indefinitely.
|
|
|
|
### 8.2 Scalability
|
|
|
|
The system shall support configurable concurrency, multi-model execution, and task fan-out without requiring per-mission custom orchestration code.
|
|
|
|
### 8.3 Security
|
|
|
|
The system shall use external policy controls for sensitive tool and network operations.
|
|
|
|
### 8.4 Privacy
|
|
|
|
The system shall classify mission and data sensitivity and route high-sensitivity work to approved model paths only.
|
|
|
|
### 8.5 Observability
|
|
|
|
The system shall emit structured traces for:
|
|
|
|
- LLM calls
|
|
- tool calls
|
|
- task durations
|
|
- mission durations
|
|
- policy decisions
|
|
- writebacks
|
|
|
|
### 8.6 Fault Tolerance
|
|
|
|
The system should support resumable mission persistence in a later phase. Sprint 1 may use simpler persistence, but the schema and API boundaries shall not block future recovery features.
|
|
|
|
### 8.7 Licensing
|
|
|
|
The system shall use only code and artifacts with clear legal provenance.
|
|
|
|
Open Multi Agent may be forked and redistributed under MIT with attribution and license preservation.
|
|
|
|
Any direct vendor Nemoclaw code incorporation shall require explicit license verification. Until then, the design shall prefer Project Velocity-owned implementations inspired by Nemoclaw concepts.
|
|
|
|
## 9. Evaluation and Testing Strategy
|
|
|
|
The system shall be validated through:
|
|
|
|
- unit tests for planners, prompt packaging, policy checks, and adapters
|
|
- integration tests for full mission execution
|
|
- golden tests for prompt package generation
|
|
- replay tests for research and librarian flows
|
|
- failure injection tests
|
|
- performance tests on fan-out missions
|
|
- security tests for blocked tools and blocked egress
|
|
|
|
Acceptance should be measured per mission class, not only at framework level.
|
|
|
|
## 10. Migration and Fork Plan
|
|
|
|
### 10.1 Fork Strategy
|
|
|
|
The fork shall preserve upstream attribution and license files from Open Multi Agent.
|
|
|
|
The fork should remain isolated under a dedicated service or package boundary so upstream changes can still be reviewed selectively.
|
|
|
|
### 10.2 Compatibility Strategy
|
|
|
|
The fork should preserve the useful Open Multi Agent primitives:
|
|
|
|
- agent config model
|
|
- orchestrator model
|
|
- task queue model
|
|
- tool abstraction
|
|
- MCP connectivity
|
|
|
|
The fork should add Project Velocity-specific layers without tightly coupling them into upstream core classes unless necessary.
|
|
|
|
### 10.3 Contribution Strategy
|
|
|
|
The fork should define:
|
|
|
|
- contribution guidelines
|
|
- interface boundaries
|
|
- extension points for new ant roles
|
|
- prompt registry contribution rules
|
|
|
|
## 11. Open Questions
|
|
|
|
The following items require explicit decisions before implementation hardens:
|
|
|
|
- exact runtime boundary between TypeScript colony service and Python backend
|
|
- persistence backend for mission artifacts
|
|
- policy engine ownership split between Nemoclaw-derived logic and colony review logic
|
|
- how much of research browsing should be headless first versus GUI capable
|
|
- whether high-risk missions use human approval by default
|
|
|
|
## 12. Acceptance Criteria
|
|
|
|
The SRS is satisfied when an initial implementation can:
|
|
|
|
- accept a mission
|
|
- plan a task DAG
|
|
- generate prompt packages
|
|
- route internal and external context
|
|
- execute workers in parallel
|
|
- aggregate and review results
|
|
- expose audit traces
|
|
- enforce policy boundaries
|
|
- integrate with at least Oracle and CRM through explicit adapters
|