quantskills/agent-quantspace/factor-mining

Factor Mining

skills/factor_mining is the Agent collaboration and research-governance boundary for market-panel factor mining. It owns versioned research objects, abstract ports, and this role/task protocol. It does not implement factor math, IC / turnover / cost statistics, static leakage checks, backtests, platform SDKs, or strategy-domain logic.

Generator roles may create arbitrary Python factor implementations in the appropriate strategies/<domain>/mined_factors/ package. A FactorSpec points to the generated callable by importable module/name; factor execution is not restricted to skills.compute.indicators. Generated functions may reuse skills.compute, pandas/numpy, or implement completely new formulas.

Dependency direction

factor_mining -> compute / analyze / store
analyze -> backtest
skills/* must never import strategies/*

Adapters that implement ports live on the factor_mining side and call outward. compute, analyze, store, and report must not depend on a Controller or Agent runtime.

Public Python API

from skills.factor_mining import (
    ResearchBrief,
    FactorSpec,
    FactorComputeRequest,
    FactorExecutionResult,
    FactorExecutionAdapter,
    DataManagerArtifactStore,
    EvaluationRequest,
    EvaluationReport,
    ReviewReport,
    PoolDecision,
    AgentTaskView,
    TaskLease,
    AgentTaskResult,
    ResearchDecision,
    FreezeManifest,
    OOSAuthorization,
    OOSAttempt,
    OOSResult,
    FactorExecutionPort,
    AnalyzePort,
    ArtifactStorePort,
    ReportPort,
    ResearchController,
    CommandRequest,
    ResearchRunStatus,
    CandidateStatus,
)

skills.factor_mining.adapters provides deterministic adapters that implement FactorExecutionPort and ArtifactStorePort against skills.compute / skills.store. AnalyzeAdapter is a thin mapper over skills.analyze.AnalyzeFacade that implements AnalyzePort and translates analyze-native findings/metrics into EvaluationReport / MetricFact / RuleCheck / EvidenceRef. ResearchController plus pure state / budget / policies / isolation / snapshots modules provide explicit commands, optimistic versions, idempotency, atomic budget leases, sealed fail-closed task views, append-only hash-chained events, and Human Gate-1 → FreezeManifest. A narrow trusted path follows the freeze: authorize_oos → complete_oos → record_gate2_approval → promote / reject_run. The Controller derives the one-shot key from frozen run/candidate/manifest/sealed-split lineage, writes a sealed append-only started attempt before calling either port, and never retries that key after a crash or terminal failure. OOS request construction is an injected trusted factory and must exact-bind the manifest; callers cannot supply split, threshold, compute, or evaluation settings. OOS results, attempt ledgers, Gate-2 approvals, and release knowledge are sealed reference closures: they never become task inputs, generator/reviewer context, or revision inputs. The manifest freezes the trusted evaluation_protocol_id independently from the Analyze engine version and records each threshold's official Analyze fact and comparison operator (rank_ic_ir, coverage_worst, or group_turnover_mean). OOS evidence and native artifacts remain separate typed reference collections. ResearchController.build_release_report_request(...) is the separate trusted ReportPort hand-off: it closes over the Brief, FactorSpec, manifest, authorization, optional OOSResult/evidence, both approvals, attempt ledger, and terminal knowledge refs, without serializing panel values into a task or log.

Schema version

SCHEMA_VERSION is "1.4.0"; every contract object and event rejects any other schema_version, and there are no legacy imports, compatibility wrappers, or permissive replay fallbacks. EvaluationReport carries exact request lineage; task views bind parent_task_id and input hashes; FreezeManifest freezes evaluation_protocol_id and canonical oos_metric_selectors; OOSAttempt is content-addressed; OOSResult keeps evidence and artifact references in separate collections. Objects or event chains persisted under another schema version must be migrated explicitly outside the Controller or continued as a new versioned run; runtime replay fails closed on any other shape.

Ports

Research Controller

ResearchController.handle(CommandRequest) is the only mutation entrypoint. It orchestrates AnalyzePort.preflight → FactorExecutionPort.execute → AnalyzePort.evaluate → AnalyzePort.compare_to_pool and fail-fast rejects on hard failures. It does not compute IC/robustness/backtests. State lives in namespaced snapshot cache + append-only controller_event artifacts (hash chain is authoritative). Concurrent commands CAS on expected next-version slots via put_if_absent; port-bearing commands claim started/idempotency before external calls and persist FailureCode.RECOVERY_REQUIRED without auto-recompute. DataManagerArtifactStore.put_if_absent / envelope_hash provide cross-process append-only semantics. Sealed capability is judged from trusted store meta plus namespace/hash checks; Gate-1 requires an injected verifier. Replay is fail-closed: each command's complete input/output-ref lists must exact-match its reconstructed state transition. Controller replay additionally revalidates task-authorized refs and re-derives Gate-1 / FreezeManifest authority from trusted storage, so recomputing an event-chain hash cannot authorize a fresh ref, lease, approval, or manifest. Budget reserve/settle/release is atomic per command; duplicate (run_id, aggregate_id, idempotency_key) replays the prior result without re-calling ports.

Adapters

skills.compute.wrappers.Factor never writes artifacts. The execution adapter does write through the configured store when producing a successful FactorExecutionResult. Successful results carry first-class brief_ref, data_version, split_id, and immutable values_content_hash / valid_mask_content_hash (canonical series_to_payload digests) inside the envelope identity. Failed results set those content hashes to None. Compute/store adapters must not statically depend on a particular strategies module or import skills.analyze; the formula resolver dynamically imports the caller-selected FunctionRef. The analyze mapping adapter may import skills.analyze only. The execution adapter supports missing_policy=keep_nan, output_dtype=float64, and index_restore_policy=restore_original_names_and_order only.

AnalyzeAdapter.preflight runs before factor execution and uses the official build_prefix_recompute_capability(factor=spec) compile path (no execution yet). Evaluate additionally passes the verified execution for fingerprint exact-match. Pool members are TypedPoolMember(execution, values) — values content must exact-match execution.values_content_hash; execution.brief_ref must exact-equal request.brief_ref (all ObjectRef fields); provenance must exact-include execution.brief_ref and execution.factor_ref (not type placeholders). Pool factor_ref may differ from the candidate factor. compare_to_pool also rehashes candidate load_series values against execution.values_content_hash before calling the facade.

Trust boundary. Production resolvers (resolve_brief / resolve_factor / resolve_execution) and artifact loaders are trusted ports. ArtifactRef content hashes must be validated by a store-backed loader. In-process malicious reflection is outside the security boundary; private capability issuers only prevent public-API misuse.

Contract invariants

• Every versioned object carries schema_version and content-hash (or

envelope-fingerprint) semantics; the caller namespace travels in Provenance.namespace and the object refs, and every ref is namespace-checked.

• EvaluationReport stores deterministic MetricFact / RuleCheck / failure

only. Agent rationale and accept/reject decisions live in ReviewReport, PoolDecision, and ResearchDecision.

• FactorSpec formulas are an unrestricted importable Python function_ref or

a structured expression plus JSON params. Generated Python source belongs in strategies/ and is referenced by module/name instead of embedded text.

• Role fields are ordinary role_id strings. Python must not copy the role

catalog below as an enum, registry, or platform whitelist.

Cross-platform capability protocol

Product names in README / AGENTS.md are compatibility declarations and examples, not a runtime whitelist. This file selects behavior by capability only (native sub-agent, equivalent isolated tasks, or sequential single-agent fallback; see "Host execution protocol").

Do not encode vendor tool names, vendor parameters, SDKs, or if platform branches in Python or in this protocol. Default: sub-agents do not recursively spawn further agents. Sealed OOS data and results never enter generation, review, or debate contexts. All modes must return the same contracts and record role_id, parent task, input versions/hashes, output refs, and status.

Host execution protocol

The host main agent is the Supervisor. It reads the role blocks below and first discovers only these semantic capabilities: isolated-context creation, parallel dispatch, wait/collect, and cancellation. Select exactly one mode:

1. Native sub-agent mode when isolated contexts, parallel dispatch, and

wait/collect are all available.

1. Equivalent isolated-task mode when isolated contexts and collection are

available but native dispatch semantics are not.

1. Sequential fallback otherwise, rebuilding the same minimum authorized

view before each role step and keeping generation separate from review.

This is capability discovery, not an instruction to implement an agent runtime inside Python. In every mode, preserve the SKILL declaration order for stable task ids, collection order, audit keys, and summaries; completion timing must never affect candidate ordering, budget use, or the resulting contracts.