factor_mining

Files (24)

• SKILL.md
• __init__.py
• __init__.py · adapters/
• analyze.py · adapters/
• compute.py · adapters/
• execution_identity.py · adapters/
• failure_codes.py · adapters/
• formula.py · adapters/
• panel.py · adapters/
• series_codec.py · adapters/
• store.py · adapters/
• budget.py
• contracts.py
• controller.py
• event_chain.py
• events.py
• identity.py
• isolation.py
• objects.py
• policies.py
• ports.py
• replay_semantics.py
• snapshots.py
• state.py

SKILL.md (first lines)

# 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

```text
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

```python
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

| Port | Caller | Responsibility |
|------|--------|----------------|
| `FactorExecutionPort` | Controller | Execute a compute-compatible `FactorSpec` |
| `AnalyzePort` | Controller | `preflight` / `evaluate` / `compare_to_pool` |
| `ArtifactStorePort` | Controller | Persist research artifacts under caller namespace |
| `ReportPort` | Release/report flow | Render reports from formal refs and facts |

### 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

From quantskills/agent-quantspace, GPL-3.0.

More from quantskills/agent-quantspace