This repository contains a small, personal proof-of-concept for a Multi-Agent Fairness Governor.

The goal is to experiment with a lightweight component that can:

• Coordinate multiple worker agents competing for tasks
• Apply simple fairness rules (e.g., prevent starvation, enforce quotas)
• Provide basic metrics and summaries of how tasks were allocated
• Append a minimal evidence record of allocation runs

This is a personal R&D prototype, not a production scheduling or orchestration system.

• Explore how a small "governor" can:
  • Receive a stream or batch of tasks
  • Route tasks to agents based on policy (priority + fairness rules)
  • Track simple allocation metrics (task counts, wait times)
• Keep the implementation small and understandable, focused on patterns rather than infrastructure.

• Full workflow engine or job scheduler
• Distributed coordination across multiple machines
• Complex SLAs or real-time guarantees

• Initial specification (SPEC.md)
• Minimal flow: task set + agent set -> governed allocation
• Basic metrics and summary output
• Evidence log of allocation runs
• Basic CLI
• Run instructions in README

• SPEC.md -- detailed specification for this prototype
• DISCLAIMER.md -- IP and usage disclaimer
• memory/constitution.md -- constraints/instructions for IDE agents
• src/ -- Python implementation
  • models.py -- dataclasses for Task, Agent, PolicyConfig, AllocationDecision, AllocationMetrics, EvidenceEntry
  • loader.py -- JSON/YAML input loaders with validation
  • allocator.py -- deterministic weighted round-robin allocator
  • metrics.py -- fairness metrics computation and labeling
  • evidence.py -- append-only JSONL evidence logging
  • cli.py -- Click CLI entry point
• fixtures/ -- sample input data (tasks, agents, policy configs)
• tests/ -- pytest test suite

• Python 3.8+
• Dependencies: click, pyyaml, pytest

pip install -r requirements.txt

python -m src allocate \
  --tasks fixtures/tasks.json \
  --agents fixtures/agents.json \
  --policy fixtures/policy.json

This outputs an allocation map and fairness metrics to stdout.

python -m src allocate \
  --tasks fixtures/tasks.json \
  --agents fixtures/agents.json \
  --policy fixtures/policy.json \
  --out allocation.json

python -m src allocate \
  --tasks fixtures/tasks.json \
  --agents fixtures/agents.json \
  --policy fixtures/policy.json \
  --log evidence.jsonl

Each run appends a single JSONL line containing the timestamp, policy identifier, task/agent counts, skew ratio, and fairness label.

{
  "allocation": [
    { "task_id": "t2", "agent_id": "agent-a" },
    { "task_id": "t5", "agent_id": "agent-b" },
    { "task_id": "t1", "agent_id": "agent-b" },
    { "task_id": "t3", "agent_id": "agent-c" },
    { "task_id": "t6", "agent_id": "agent-a" },
    { "task_id": "t4", "agent_id": "agent-b" }
  ],
  "metrics": {
    "task_count_per_agent": {
      "agent-a": 2,
      "agent-b": 3,
      "agent-c": 1
    },
    "max_tasks": 3,
    "min_tasks": 1,
    "skew_ratio": 3.0,
    "fairness_label": "strong_imbalance"
  }
}

python -m pytest tests/ -v

The allocator uses a weighted round-robin strategy:

1. If respect_priority is enabled in the policy, tasks are sorted by priority (high > normal > low). Within the same priority level, original order is preserved (stable sort).
2. An agent rotation is built by expanding each agent by its weight. For example, agents [A(w=1), B(w=2), C(w=1)] produce the rotation [A, B, B, C].
3. A round-robin pointer iterates over the rotation. For each task, the allocator picks the next agent that has not reached its capacity limit.
4. If no agent can accept a task (all at capacity), the task is marked as unassigned.

The allocator is deterministic: given the same inputs, it always produces the same output.

• task_count_per_agent -- number of tasks assigned to each agent
• max_tasks / min_tasks -- the highest and lowest task counts
• skew_ratio -- max_tasks / max(1, min_tasks)
• fairness_label:
  • balanced -- skew_ratio <= 1.5
  • mild_imbalance -- 1.5 < skew_ratio <= max_skew_ratio (from policy)
  • strong_imbalance -- skew_ratio > max_skew_ratio

All inputs are JSON files. YAML is also supported if PyYAML is installed.

See the fixtures/ directory for example files:

• fixtures/tasks.json -- sample tasks with priorities
• fixtures/agents.json -- sample agents with weights
• fixtures/agents_with_capacity.json -- agents with capacity limits
• fixtures/policy.json -- policy with priority ordering enabled
• fixtures/policy_no_priority.json -- policy with priority ordering disabled

See SPEC.md for detailed requirements.