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

10 KiB

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

TypeScript runtime validation in colony service
Python root payload validation before persistence
database-level required column and foreign key validation

16. Immediate Implementation Order

Implement schemas in this order:

mission envelope
task graph
prompt package
worker result
review packet
policy decision
librarian pass
research artifact
aggregation packet
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.

10 KiB Raw Blame History