# scpz24/requirementseeker architecture

> Architecture diagram of the GitHub repository scpz24/requirementseeker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scpz24/requirementseeker
- Repository: https://github.com/scpz24/requirementseeker

## Overview

RequirementSeeker is a set of Python packages for collecting and preparing comment datasets and for developing a requirements-analysis agent. The README explicitly says there is not yet a complete application or integrated analysis pipeline, so this map shows package capabilities without implying a connected end-to-end runtime. The sampled agent orchestrator supports its internal analysis-stage links; collector and dataset-tool wiring is less fully evidenced, so uncertain connections are omitted.

Main entry points: [`packages/agent/src/requirementseeker_agent/pipeline/m2.py`](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/m2.py) (M2 orchestrator), [`packages/collector/src/requirementseeker_collector/runner.py`](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/runner.py) (Collection runner), [`packages/dataset-tools/src/requirementseeker_dataset/sanitize.py`](https://github.com/scpz24/requirementseeker/blob/main/packages/dataset-tools/src/requirementseeker_dataset/sanitize.py) (Sanitization), [`packages/agent/src/requirementseeker_agent/sampling/policy.py`](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/sampling/policy.py) (Quality and sampling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collect["Collection"]
  node_collector_cli["Collector CLI<br/>[cli.py]"]
  node_planning["Collection planning<br/>[planning.py]"]
  node_discovery["Candidate discovery<br/>[discovery.py]"]
  node_coverage["Coverage validation<br/>[coverage.py]"]
  node_runner["Collection runner<br/>[runner.py]"]
  node_adapters["Platform adapters"]
  node_raw_contracts["Raw data contracts<br/>[contracts.py]"]
end

subgraph group_prepare["Dataset preparation"]
  node_sanitize["Sanitization<br/>[sanitize.py]"]
end

subgraph group_agent["Analysis agent"]
  node_sampling["Quality and sampling<br/>[policy.py]"]
  node_request_contracts["Analysis contracts<br/>[requests.py]"]
  node_orchestrator["M2 orchestrator<br/>[m2.py]"]
  node_signals["Signal extraction<br/>[signals.py]"]
  node_clustering["Signal clustering<br/>[clusters.py]"]
  node_consensus["Consensus rules<br/>[consensus.py]"]
  node_runtime["Budget and cache"]
  node_results["Analysis results<br/>[results.py]"]
end

node_operator(("Operator"))
node_platforms(("Video platforms"))
node_raw_data[("Raw collection data")]
node_host(("Host application"))
node_model["Model gateway<br/>[types.py]"]

node_operator -->|"invokes"| node_collector_cli
node_platforms -->|"serves pages"| node_runner
node_runner -->|"parses responses"| node_adapters
node_runner -->|"builds records"| node_raw_contracts
node_runner -->|"writes collection"| node_raw_data
node_raw_data -->|"provides raw input"| node_sanitize
node_operator -->|"approves plan"| node_sanitize
node_sanitize -->|"provides sanitized manifest"| node_sampling
node_host -->|"requests sampling"| node_sampling
node_sampling -->|"returns plan"| node_host
node_host -->|"submits request"| node_orchestrator
node_orchestrator -->|"validates input"| node_request_contracts
node_orchestrator -->|"extracts signals"| node_signals
node_orchestrator -->|"clusters signals"| node_clustering
node_orchestrator -->|"checks clusters"| node_consensus
node_signals -->|"invokes model"| node_model
node_clustering -->|"invokes model"| node_model
node_orchestrator -->|"uses budget and cache"| node_runtime
node_orchestrator -->|"produces result"| node_results

click node_collector_cli "https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/cli.py"
click node_planning "https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/planning.py"
click node_discovery "https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/candidates/discovery.py"
click node_coverage "https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/candidates/coverage.py"
click node_runner "https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/runner.py"
click node_adapters "https://github.com/scpz24/requirementseeker/tree/main/packages/collector/src/requirementseeker_collector/adapters"
click node_raw_contracts "https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/contracts.py"
click node_sanitize "https://github.com/scpz24/requirementseeker/blob/main/packages/dataset-tools/src/requirementseeker_dataset/sanitize.py"
click node_sampling "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/sampling/policy.py"
click node_request_contracts "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/contracts/requests.py"
click node_orchestrator "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/m2.py"
click node_signals "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/signals.py"
click node_clustering "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/clusters.py"
click node_consensus "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/rules/consensus.py"
click node_model "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/model/types.py"
click node_runtime "https://github.com/scpz24/requirementseeker/tree/main/packages/agent/src/requirementseeker_agent/runtime"
click node_results "https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/contracts/results.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_collector_cli,node_planning,node_discovery,node_coverage,node_runner,node_adapters,node_raw_contracts toneBlue
class node_sanitize,node_raw_data toneAmber
class node_sampling,node_request_contracts,node_orchestrator,node_signals,node_clustering,node_consensus,node_runtime,node_results toneMint
class node_operator,node_platforms,node_host,node_model toneIndigo
```

## Components

### Collection

- [Collector CLI](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/cli.py): `packages/collector/src/requirementseeker_collector/cli.py`
- [Collection planning](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/planning.py): `packages/collector/src/requirementseeker_collector/planning.py`
- [Candidate discovery](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/candidates/discovery.py): `packages/collector/src/requirementseeker_collector/candidates/discovery.py`
- [Coverage validation](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/candidates/coverage.py): `packages/collector/src/requirementseeker_collector/candidates/coverage.py`
- [Collection runner](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/runner.py): `packages/collector/src/requirementseeker_collector/runner.py`
- [Platform adapters](https://github.com/scpz24/requirementseeker/tree/main/packages/collector/src/requirementseeker_collector/adapters): `packages/collector/src/requirementseeker_collector/adapters`
- [Raw data contracts](https://github.com/scpz24/requirementseeker/blob/main/packages/collector/src/requirementseeker_collector/contracts.py): `packages/collector/src/requirementseeker_collector/contracts.py`

### Dataset preparation

- [Sanitization](https://github.com/scpz24/requirementseeker/blob/main/packages/dataset-tools/src/requirementseeker_dataset/sanitize.py): `packages/dataset-tools/src/requirementseeker_dataset/sanitize.py`

### Analysis agent

- [Quality and sampling](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/sampling/policy.py): `packages/agent/src/requirementseeker_agent/sampling/policy.py`
- [Analysis contracts](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/contracts/requests.py): `packages/agent/src/requirementseeker_agent/contracts/requests.py`
- [M2 orchestrator](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/m2.py): `packages/agent/src/requirementseeker_agent/pipeline/m2.py`
- [Signal extraction](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/signals.py): `packages/agent/src/requirementseeker_agent/pipeline/signals.py`
- [Signal clustering](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/pipeline/clusters.py): `packages/agent/src/requirementseeker_agent/pipeline/clusters.py`
- [Consensus rules](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/rules/consensus.py): `packages/agent/src/requirementseeker_agent/rules/consensus.py`
- [Budget and cache](https://github.com/scpz24/requirementseeker/tree/main/packages/agent/src/requirementseeker_agent/runtime): `packages/agent/src/requirementseeker_agent/runtime`
- [Analysis results](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/contracts/results.py): `packages/agent/src/requirementseeker_agent/contracts/results.py`

### Other components

- **Operator**
- **Video platforms**
- **Raw collection data**
- **Host application**
- [Model gateway](https://github.com/scpz24/requirementseeker/blob/main/packages/agent/src/requirementseeker_agent/model/types.py): `packages/agent/src/requirementseeker_agent/model/types.py`

## Connections

- Operator → Collector CLI: invokes
- Video platforms → Collection runner: serves pages
- Collection runner → Platform adapters: parses responses
- Collection runner → Raw data contracts: builds records
- Collection runner → Raw collection data: writes collection
- Raw collection data → Sanitization: provides raw input
- Operator → Sanitization: approves plan
- Sanitization → Quality and sampling: provides sanitized manifest
- Host application → Quality and sampling: requests sampling
- Quality and sampling → Host application: returns plan
- Host application → M2 orchestrator: submits request
- M2 orchestrator → Analysis contracts: validates input
- M2 orchestrator → Signal extraction: extracts signals
- M2 orchestrator → Signal clustering: clusters signals
- M2 orchestrator → Consensus rules: checks clusters
- Signal extraction → Model gateway: invokes model
- Signal clustering → Model gateway: invokes model
- M2 orchestrator → Budget and cache: uses budget and cache
- M2 orchestrator → Analysis results: produces result