sagnik/Project_Velocity

Fork 2

Files

Sagnik 4b21c2cad6 feat: Oracle CRM Page, Synthetic Client Data and Live Snapshot when hitting emotion hotpoint

2026-04-19 00:43:01 +05:30

9.9 KiB

Raw Blame History

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

9.9 KiB Raw Blame History