swarm_predict

Swarm Prediction Specialist

Overview

swarm_predict mirrors aggregation patterns from 666ghj/MiroFish. It creates configurable virtual model descriptors, generates numeric fixture values from the target string, and resolves an arithmetic consensus through weighted aggregation and agreement scoring.

The specialist is stateless and returns a self-contained result dict. The standalone aggregation tool also supports caller-supplied numeric or categorical values through weighted vote, majority vote, or simple mean.

The current end-to-end specialist does not call any model. It generates target-derived numeric fixture values, then exercises the real aggregation functions. Its result is not a forecast.

Prerequisites

• Use Python 3.11+ in a local OSS Agent Lab checkout and run pip install -e ..
• Provide a test target, a positive swarm size, and a threshold between 0 and 1.
• Read the runtime contract for aggregation semantics.

Capabilities

• predict: Derive numeric fixture values from a target and aggregate them.
• ensemble: Combine N synthetic or caller-supplied values.
• swarm_intelligence: Exercise virtual model descriptors without model execution.
• consensus: Compute an agreement ratio and blended arithmetic confidence.

Tools

Tool	Description	Side Effects
create_prediction_swarm	Initialise N virtual model descriptors	None
aggregate_predictions	Merge individual predictions via weighted/majority/mean vote	None
evaluate_consensus	Score agreement ratio and emit a recommendation	None

Parameters

Request-level (intent.parameters)

Key	Type	Default	Description
target	str	(query.user_input)	Prediction target; falls back to the raw user query
num_models	int	5	Swarm size
method	str	"weighted_vote"	Aggregation strategy: weighted_vote, majority_vote, mean
threshold	float	0.7	Minimum agreement ratio for consensus to be declared

Aggregation methods

• weighted_vote — weighted average using each model's confidence as its weight. Preferred for numeric targets where confidence is informative.
• majority_vote — discrete winner-takes-all; numeric values are averaged as a fallback. Suited for classification targets.
• mean — unweighted average. Baseline; useful for ablation.

Output

{
    "target": str,
    "predictions": list[dict],      # individual model outputs
    "consensus": float | str,       # aggregated prediction
    "confidence": float,            # blended confidence score 0-1
    "recommendation": str,          # "high_confidence_proceed" | "moderate_confidence_review" | "low_confidence_abstain"
    "swarm_id": str,                # UUID for this swarm instance
}

Instructions

1. Choose a target, swarm size, aggregation method, and consensus threshold.
2. Run the specialist for synthetic numeric fixtures, or call aggregation with caller-supplied values.
3. Report agreement and confidence as arithmetic over inputs, not calibrated predictive accuracy.
4. Do not use the recommendation for financial, medical, safety, or other consequential decisions.

Examples

Python API

import asyncio
from agents.specialists.swarm_predict.agent import SwarmPredictSpecialist
from oss_agent_lab.contracts import Intent, Query, SpecialistRequest

specialist = SwarmPredictSpecialist()

request = SpecialistRequest(
    intent=Intent(
        action="predict",
        domain="swarm_intelligence",
        confidence=0.9,
        parameters={"target": "BTC/USD price in 24h", "num_models": 7},
    ),
    query=Query(user_input="BTC/USD price in 24h"),
    specialist_name="swarm_predict",
)

response = asyncio.run(specialist.execute(request))
print(response.result["consensus"], response.result["recommendation"])

CLI

oss-lab run swarm_predict "BTC/USD price in 24h"

With custom parameters

oss-lab run swarm_predict "next quarter revenue" \
  --param num_models=10 \
  --param method=majority_vote \
  --param threshold=0.8

Error Handling

• Reject a swarm smaller than one, an empty prediction list, unknown method, or invalid threshold.
• Validate caller-supplied prediction provenance before interpreting a consensus.
• Treat high_confidence_proceed as a test label, not authorization to act.

Resources

Wraps 666ghj/MiroFish. The local implementation only exercises virtual descriptors and aggregation. See the runtime contract.