task-scorer

Shared scoring and routing engine for task complexity estimation.

Zero-dependency Python package that provides weighted multi-dimension keyword scoring with sigmoid confidence calibration. Consolidates scoring logic from BFAgent (TestRequirement, LLMRouter) and Orchestrator MCP (analyzer).

ADR: ADR-023 Shared Scoring and Routing Engine

Installation

# From git (recommended for Docker)
pip install "task-scorer @ git+ssh://git@github.com/achimdehnert/platform.git@main#subdirectory=packages/task_scorer"

# Local development
pip install -e ".[dev]"

Usage

from task_scorer import score_task, ScoringConfig, Tier

# With defaults
result = score_task("fix the authentication bug in the API")
print(result.top_type)    # "security"
print(result.tier)        # Tier.HIGH
print(result.confidence)  # 0.87
print(result.signals)     # ["security(auth)", "bug(fix)"]
print(result.is_ambiguous)  # False

# With custom config (e.g. from DB lookup tables)
config = ScoringConfig(
    keywords={"security": ["auth", "cve", "credential"]},
    weights={"security": 2.0},
    tier_boundaries=(0.5, 1.5),
)
result = score_task("check auth flow", config=config)

# With structured metadata
result = score_task(
    "refactor the authentication module",
    category="security",
    acceptance_criteria_count=5,
    files_affected=8,
)

API

score_task(description, config=None, category=None, acceptance_criteria_count=0, files_affected=0) -> ScoringResult

Main entry point. Scores a task description against all configured task types using weighted keyword matching.

ScoringResult

ScoringConfig

Testing

cd packages/task_scorer
pip install -e ".[dev]"
python3 -m pytest tests/ -v

Architecture

src/task_scorer/
├── __init__.py    # Public API exports
├── types.py       # ScoringConfig, ScoringResult, Tier, DEFAULT_KEYWORDS
└── scorer.py      # score_task, _score_all_types, _sigmoid_confidence

• Zero dependencies — stdlib only (math, dataclasses, enum)
• Frozen dataclasses — immutable config and results
• Config injection — defaults in code, DB-driven override via ScoringConfig
• Tenant-agnostic — pure function, no database access