Corporate Venturing Toolkit — Implementation Guide

conda activate cv_env
pip install -r requirements.txt
export TOKENIZERS_PARALLELISM=false        # silence HuggingFace fork warning

# API key — stored in a git-ignored .env at repo root (loaded by cv_config.load_dotenv())
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env

Build the scoring rubrics once (converts the framework definitions into scoring bands + key indicators, cached in .cv_cache/):

python cv_toolkit.py rubrics      # build outputs/rubrics.json from framework/*.txt   (cv_framework.py)
python cv_toolkit.py describe     # add plain-English brief_descriptions (Haiku)
# v2 rubrics (broader definitions) are built automatically by run_batch_v2.sh → outputs_v2/rubrics.json

Each dimension scores 0–100 (emphasis). Rubrics are conceptual guides, not vocabulary checklists — the model scores the underlying activity regardless of wording. framework/ holds detailed v1 definitions; framework_v2/ holds broader v1-paragraph definitions used by run_batch_v2.sh.

An LLM judgment, aggregated by code:

1. Assemble (code) — _scoring_prompt() packs, per dimension, the extracted evidence (verbatim sentences, key terms, financial figures), the rubric (scoring bands + brief description), and company context into one prompt.
2. Score (LLM) — Claude (temperature=0) returns per dimension an emphasis_score 0–100 (+ rank, description, top_quote, rubric_band, rationale). The number is the model's holistic judgment, anchored by explicit rubric bands: 20–39 incidental · 40–59 generic/enterprise-scale · 60–79 explicit/named/quantified · 80–100 comprehensive/strategic with metrics. No arithmetic maps evidence → score.
3. Ensemble (code) — the scoring call runs N times (default 5); _aggregate_ensemble() reports the per-dimension median (statistics.median) with min/max/std as uncertainty.
4. Rank (code) — recomputed by sorting median scores within each group (practices 1–4, activities 1–4, objectives 1–7) — not taken from the LLM.
5. Total (code) — headline = median of the per-pass totals; sum_of_medians also stored.

A hybrid: LLM-judged cells where evidence is strong, deterministic theoretical alignment everywhere else.

1. LLM cells — the scoring call also returns practice_x_objective_matrix (8 practice/activity rows × 7 objectives, 0–100) = "how strongly each row serves each objective." The model typically fills only rows with strong evidence; ensemble medians these cells.
2. Code fallback fill (cv_analyzer.py) — any row the LLM left empty/zero is filled from the rubric's fixed cross_objective_relevance map (high/medium/low/none → 70/40/20/0), scaled by the dimension's emphasis score:

   scale = 0.25 + 0.75 × (emphasis_score / 100)
   cell  = relevance_number × scale

   So a 0-scored dimension still shows its theoretical alignment at 25% intensity; an 80-scored one at ~85%. Rows the LLM scored keep the LLM values; the rest get this computation.

The cross_objective_relevance map is authored by the LLM once when rubrics are built (cv_framework.py), then frozen in rubrics.json and applied deterministically at scoring time.

Bottom line: scoring and P×O alignment-where-evidence-exists are LLM judgments; aggregation (median across passes), ranking, totals, and the theoretical P×O fill for unscored rows are deterministic code.

Caches (built once, reused)

Per company — outputs_v2/<TICKER>/

Curated web (optional) — scraped/<TICKER>/

Portfolio — outputs_v2/

Single company (full chain)

# 1) fetch + preprocess (Steps 1–2)
python cv_toolkit.py preprocess --ticker GOOGL --output outputs

# 2) [optional] scrape curated web (Step 6a)
python cv_toolkit.py scrape --ticker GOOGL

# 3) analyze: Steps 3–11 (windowed extraction, ensemble scoring, investment_and_funds, visuals)
python cv_toolkit.py --output outputs_v2 --rubrics outputs_v2/rubrics.json --ensemble 5 \
    analyze --ticker GOOGL --company "Alphabet Inc." \
    --file outputs/GOOGL_narrative.txt --with-scraped --force

# 4) ensemble table + figure (Step 11)
python ensemble_report.py outputs_v2/GOOGL

# 5) portfolio aggregation (Step 12)
python cv_toolkit.py --output outputs_v2 --rubrics outputs_v2/rubrics.json csv
python cv_toolkit.py --output outputs_v2 --rubrics outputs_v2/rubrics.json portfolio-report

Whole portfolio (batch — runs Steps 1–12 for every company)

bash run_batch_v2.sh --force                 # all companies, v2 framework → outputs_v2/
bash run_batch_v2.sh --ticker GOOGL --force  # single company through the v2 batch

Today the LLM both reads the evidence and emits the 0–100 number (the judgment is opaque). The hybrid splits these:

• LLM = perception → extracts a few well-defined, bounded sub-signals per dimension.
• Code = judgment → a transparent formula maps those signals → 0–100 (auditable, reproducible, tunable).

Categorical buckets are far more stable across runs than a free 0–100 number → less ensemble noise.

score = BASE[directness]
      + W_spec     * LEVEL[specificity]
      + W_evidence * min(evidence_count, CAP)/CAP
      + W_fin      * financials_present
score = clamp(score, 0, 100)

Every score then decomposes traceably, e.g. CVC = 72 = direct(40) + named+quantified(20) + evidence 8/cap(8) + financials(4).

final = α · formula_score + (1 − α) · llm_holistic_score

α=1 → fully transparent/reproducible; α=0 → today's behaviour; in between → hybrid. Plus an optional LLM "override flag" for genuine edge cases the formula misses.

Replace hand-set weights with a small ordinal/linear model fit on a labelled sample (human scores, or current LLM scores as a starting target). LLM features → interpretable coefficients → score, making scoring a defensible, reportable model.

The fallback fill already does this (relevance × emphasis-scale). The hybrid would make the whole matrix formula-based for consistency: cell = f(row emphasis, cross_objective_relevance, objective emphasis, evidence co-occurrence) — removing the "LLM cells vs. coded cells" split.

Footprint when implemented: new extraction schema, a score_from_features() in cv_analyzer, weights in cv_config, keep the current LLM-score path behind the α blend, and a harness comparing formula vs. LLM scores.