sayan/Project_Velocity
1
1
Fork 0
forked from sagnik/Project_Velocity
Code Issues Pull Requests Activity
Files
269591a3ccb377c7b7528a8bf4f26370a090d383
Project_Velocity/.Agent Context/Sprint 1/Biomimetic Agentic Orchestration Layer/Mission Contracts and JSON Schemas Blueprint.md

458 lines
10 KiB
Markdown
Raw Blame History

# Mission Contracts and JSON Schemas Blueprint
**Date:** 2026-04-14
**Status:** Draft implementation artifact
**Purpose:** Define the concrete contract model, JSON payload shapes, schema boundaries, versioning rules, and validation plan for the colony orchestration layer.
## 1. Purpose
This document converts the colony architecture into explicit contracts. The system must not rely on informal prompt chaining between stages. Every stage must read and write a typed artifact.
## 2. Contract Design Rules
### 2.1 Version Every Artifact
Every artifact must carry:
- `schema_name`
- `schema_version`
This is mandatory from day one so prompt package evolution and mission replay do not become brittle later.
### 2.2 Keep Root Metadata on Every Artifact
Every artifact should include:
- `mission_id`
- `tenant_id`
- `actor_id`
- `created_at`
- `producer`
This prevents orphan artifacts and makes debugging much easier.
### 2.3 Store Canonical Payloads as JSON
Root PostgreSQL persistence should store the canonical artifact payload in `jsonb`, even if some fields are also denormalized for indexing.
### 2.4 Prefer Small Composable Artifacts
Do not use one giant colony state blob. The correct design is multiple artifacts with explicit linkage.
## 3. Core Artifact Set
Phase 1 artifact set:
- `mission_envelope`
- `mission_task_graph`
- `prompt_package`
- `research_artifact`
- `librarian_pass`
- `worker_result`
- `aggregation_packet`
- `review_packet`
- `policy_decision`
- `writeback_proposal`
## 4. Mission Envelope Schema
### 4.1 Purpose
Defines the normalized mission before decomposition.
### 4.2 Suggested JSON Shape
```json
{
"schema_name": "mission_envelope",
"schema_version": "v1",
"mission_id": "uuid",
"mission_type": "oracle_advisory",
"origin_surface": "oracle",
"tenant_id": "tenant_velocity",
"actor_id": "oracle_operator",
"actor_role": "sales_director",
"user_goal": "Summarize the highest intent waterfront prospects and recommend next actions.",
"normalized_goal": "Produce a prioritized lead intelligence brief for waterfront prospects with actions.",
"risk_level": "medium",
"sensitivity_class": "internal_business",
"time_budget_ms": 45000,
"token_budget": 180000,
"requested_outputs": [
"reviewed_summary",
"writeback_proposal"
],
"context_refs": {
"lead_ids": ["lead_123"],
"page_id": null,
"campaign_ids": []
},
"created_at": "2026-04-14T12:00:00Z",
"producer": "python_root_gateway"
}
```
### 4.3 Required Fields
Required:
- `schema_name`
- `schema_version`
- `mission_id`
- `mission_type`
- `origin_surface`
- `tenant_id`
- `actor_id`
- `user_goal`
- `normalized_goal`
- `risk_level`
- `sensitivity_class`
- `created_at`
- `producer`
## 5. Mission Task Graph Schema
### 5.1 Purpose
Defines the DAG produced by the planner.
### 5.2 Suggested JSON Shape
```json
{
"schema_name": "mission_task_graph",
"schema_version": "v1",
"mission_id": "uuid",
"tasks": [
{
"task_id": "task_plan_01",
"role_type": "prompt_master",
"objective": "Prepare role-specific prompt packages for all execution tasks.",
"depends_on": [],
"required_capabilities": ["prompt_templates", "task_prompting"],
"allowed_tools": [],
"required_data_scopes": ["mission_metadata"],
"success_criteria": [
"prompt packages exist for all downstream tasks"
]
}
],
"created_at": "2026-04-14T12:00:02Z",
"producer": "planner_agent"
}
```
### 5.3 Required Rules
- every `task_id` must be unique within mission
- `depends_on` must only reference existing task IDs
- role types must be from an allowed enum in Phase 1
Phase 1 allowed role types:
- `planner`
- `prompt_master`
- `researcher`
- `librarian`
- `worker`
- `aggregator`
- `reviewer`
## 6. Prompt Package Schema
### 6.1 Purpose
Defines the exact worker-facing prompt instruction package.
### 6.2 Suggested JSON Shape
```json
{
"schema_name": "prompt_package",
"schema_version": "v1",
"mission_id": "uuid",
"task_id": "task_worker_01",
"package_id": "pkg_001",
"role_type": "worker",
"template_id": "crm_lead_intelligence_worker",
"template_version": "v1",
"examples_used": [
"crm_worker_example_01"
],
"system_prompt": "You are a lead intelligence specialist...",
"task_prompt": "Analyze the provided lead context...",
"constraints": {
"must_cite_sources": true,
"must_not_writeback_directly": true
},
"tool_scope": [
"crm_search",
"local_property_rag",
"external_search"
],
"model_route": "tier_high_reasoning",
"created_at": "2026-04-14T12:00:05Z",
"producer": "prompt_master_agent"
}
```
## 7. Research Artifact Schema
### 7.1 Purpose
Represents external evidence.
### 7.2 Suggested JSON Shape
```json
{
"schema_name": "research_artifact",
"schema_version": "v1",
"mission_id": "uuid",
"task_id": "task_research_01",
"artifact_id": "res_001",
"provider": "brave",
"query": "Dubai waterfront premium real estate 2026 demand",
"results": [
{
"title": "Market report title",
"url": "https://example.com/report",
"snippet": "Short snippet",
"source_type": "web",
"retrieved_at": "2026-04-14T12:01:00Z",
"confidence": 0.82
}
],
"created_at": "2026-04-14T12:01:01Z",
"producer": "researcher_agent"
}
```
## 8. Librarian Pass Schema
### 8.1 Purpose
Represents scoped internal routing instructions for workers.
### 8.2 Suggested JSON Shape
```json
{
"schema_name": "librarian_pass",
"schema_version": "v1",
"mission_id": "uuid",
"task_id": "task_worker_01",
"pass_id": "pass_001",
"allowed_resource_families": [
"crm.leads",
"crm.chat_logs"
],
"recommended_queries": [
{
"tool": "crm_search",
"query": "waterfront whale prospects"
}
],
"cached_previews": [
{
"label": "Lead summary",
"entity_type": "lead",
"entity_id": "lead_123",
"preview": "Whale prospect interested in marina-facing unit"
}
],
"expires_at": "2026-04-14T13:00:00Z",
"created_at": "2026-04-14T12:00:08Z",
"producer": "librarian_agent"
}
```
## 9. Worker Result Schema
### 9.1 Purpose
Represents normalized output from one worker.
### 9.2 Suggested JSON Shape
```json
{
"schema_name": "worker_result",
"schema_version": "v1",
"mission_id": "uuid",
"task_id": "task_worker_01",
"result_id": "wrk_001",
"output_text": "Lead 123 has the highest close probability...",
"structured_output": {
"priority": "high",
"recommended_action": "schedule executive follow-up"
},
"citations": [
{
"kind": "internal",
"ref": "lead_123"
}
],
"confidence": 0.79,
"tool_trace_refs": [
"toolcall_001",
"toolcall_002"
],
"created_at": "2026-04-14T12:02:10Z",
"producer": "worker_agent"
}
```
## 10. Aggregation Packet Schema
### 10.1 Purpose
Represents the synthesized draft before review.
### 10.2 Suggested JSON Shape
```json
{
"schema_name": "aggregation_packet",
"schema_version": "v1",
"mission_id": "uuid",
"packet_id": "agg_001",
"summary": "Top waterfront leads are concentrated in two whale segments...",
"evidence_matrix": [
{
"claim": "Lead 123 is high priority",
"support_refs": ["wrk_001", "lead_123"]
}
],
"contradictions": [],
"coverage_gaps": [],
"recommended_output": {
"format": "structured_brief"
},
"created_at": "2026-04-14T12:03:00Z",
"producer": "aggregator_agent"
}
```
## 11. Review Packet Schema
### 11.1 Purpose
Represents the one-pass review outcome.
### 11.2 Suggested JSON Shape
```json
{
"schema_name": "review_packet",
"schema_version": "v1",
"mission_id": "uuid",
"packet_id": "rev_001",
"review_status": "approved_with_edits",
"issues": [
{
"severity": "medium",
"message": "One recommendation needs clearer business justification."
}
],
"required_edits": [
"add one sentence linking lead score to action priority"
],
"approved_output": {
"summary": "Reviewed final answer here"
},
"created_at": "2026-04-14T12:03:20Z",
"producer": "reviewer_agent"
}
```
## 12. Policy Decision Schema
### 12.1 Purpose
Represents an explicit allow or deny decision from the guard plane.
### 12.2 Suggested JSON Shape
```json
{
"schema_name": "policy_decision",
"schema_version": "v1",
"mission_id": "uuid",
"decision_id": "pol_001",
"decision_type": "tool_scope",
"subject": "external_search",
"decision": "allow",
"reason": "mission sensitivity permits public web search",
"created_at": "2026-04-14T12:00:03Z",
"producer": "colony_policy_bridge"
}
```
## 13. Writeback Proposal Schema
### 13.1 Purpose
Represents a proposed root mutation. This is a proposal only, never a direct execution artifact.
### 13.2 Suggested JSON Shape
```json
{
"schema_name": "writeback_proposal",
"schema_version": "v1",
"mission_id": "uuid",
"proposal_id": "wb_001",
"target_entity_type": "lead",
"target_entity_id": "lead_123",
"action_type": "lead_stage_update",
"payload": {
"kanban_status": "Negotiation"
},
"requires_approval": true,
"created_at": "2026-04-14T12:03:25Z",
"producer": "reviewer_agent"
}
```
## 14. Root Table Mapping
Recommended root table to artifact mapping:
- `colony_missions` -> mission envelope
- `colony_tasks` -> task graph task records
- `colony_prompt_packages` -> prompt package
- `colony_research_artifacts` -> research artifact
- `colony_librarian_passes` -> librarian pass
- `colony_worker_results` -> worker result
- `colony_aggregation_packets` -> aggregation packet
- `colony_review_packets` -> review packet
- `colony_policy_decisions` -> policy decision
## 15. Validation Strategy
Validation should occur in three layers:
1. TypeScript runtime validation in colony service
2. Python root payload validation before persistence
3. database-level required column and foreign key validation
## 16. Immediate Implementation Order
Implement schemas in this order:
1. mission envelope
2. task graph
3. prompt package
4. worker result
5. review packet
6. policy decision
7. librarian pass
8. research artifact
9. aggregation packet
10. writeback proposal
## 17. Bottom Line
The colony will only be dependable if every stage is contract-first. This document defines the contract spine that allows the rest of the implementation to stay disciplined.
Reference in New Issue View Git Blame Copy Permalink