ranking ยท diff
git:20260819.8f0a147 to git:20260906.f9cef19
63 added, 19 removed. Audit A to A.
---
name: ranking
- description: Rank people or other supported entities against a specific objective using selected stored insights and LLM-based comparison. Use as a backend utility for workflows that need structured ranked rows or a Markdown ranking report, such as expert search or potential-investor matching.
+ description: Compare stored profiles against an objective using the shared ranking engine. Use its structured rows or Markdown adapter for expert search, potential investors, event advocates, and startup suggestions.
---
- # Skill: Ranking
+ # Ranking
- `ranking_persons(...)` returns the human-readable Markdown report.
- `rank_person_rows(...)` returns structured rows for composing other workflows
- without parsing Markdown.
+ Rank supplied profile content and explain the finalists.
- **Description:**
- Core engine to rank entities (like SICTIC members or startup profiles) against a specific objective using an LLM-powered Swiss tournament algorithm. It ranks candidates in batches of 16 by default and acts as the unified backend for skills like `expert_search`, `potential_investors`, and `suggested_startups`.
+ ## Inputs and outputs
- **Available Targets:**
- * `persons`: Resolves candidates and opt-outs against the canonical member roster, selects their stored profiles, and ranks them directly.
+ - `ranking_top_k(objective, all_profiles, top_k=16, batch_size=16)` accepts an
+ ID-to-content mapping and returns `(ranked_items, actual_count)`; items contain
+ `id`, `text` and one-based `rank`. Empty input returns `([], 0)`.
+ - `ranking_rationale(objective, ranked_items)` adds each item's `rationale`
+ in place, preserving IDs, ranks and order.
+ - `rank_person_rows(...)` returns rows with `rank`, `full_name`,
+ `email_addresses`, `linkedin_id` and `rationale`.
+ `ranking_persons(...)` renders those rows as a Markdown table.
+ Both default to `top_k=16`, `skill="investor_profile"` and
+ `member_dataset="sictic-members"`; omitted `source_datasets` uses that dataset.
- **Usage:**
- `ranking` is a backend utility and is not exposed as a harness slash command.
- For normal workflows, use the harness commands that call this engine:
- ```bash
- conda run -n sictic-env python -m skills.harness /expert_search "<STARTUP_NAME>"
- conda run -n sictic-env python -m skills.harness /potential_investors "<STARTUP_NAME>"
- ```
+ The person adapters accept optional `candidates` and `optout` lists of names,
+ emails or LinkedIn IDs. Omitted or empty candidates select the existing roster.
+ Explicit selections are matched to canonical people, then deduplicated.
- Run the ranking module directly only when debugging ranking behavior.
- Provide an objective:
+ ## Workflow and dependencies
+
+ Read the roster through the synchronous `lib.people.discovery.persons_in_dataset`
+ reader and select preferred stored profiles with `select_insights`.
+ Person ranking requires LinkedIn IDs. Apply candidate selection and opt-outs
+ before reading profile content. Names, emails and IDs in output rows come from
+ canonical `Person` objects; the model supplies ordering and rationales.
+
+ The bucketed tournament shuffles candidates, compares batches, progressively
+ retains stronger buckets, then ranks the survivors together. Selection is
+ approximate and can vary between runs; it does not guarantee the global best
+ `top_k`. Intermediate batches default to 16; the final comparison can exceed
+ that size. Return at most the requested number, limited by available survivors.
+
+ Keep domain objectives in the calling skill's configuration. This package owns
+ `ranking_top_k` and `ranking_rationale` prompts and schemas. Use shared
+ `generate_json` and its `Review` mechanism. Ranking schemas restrict IDs to the
+ supplied candidates. The existing ranking reviewer removes duplicate IDs and
+ appends missing IDs in input order; unexpected IDs require correction. Rationale
+ validation rejects missing, duplicate or unexpected IDs and blank explanations.
+
+ ## Side effects and failure behavior
+
+ The engine calls models but does not discover people, refresh profiles, ingest
+ documents, save insights or cache completed rankings. Callers own these decisions.
+ Ranking orders the supplied candidates; domain eligibility must be resolved by
+ the caller when strict exclusion is required.
+
+ Unknown explicit candidates, missing explicitly requested profiles, duplicate
+ profile IDs across source datasets, or an empty eligible profile pool raise.
+ With default roster selection, people without LinkedIn IDs or stored profiles
+ are skipped. Unresolved opt-outs log a warning. Configuration, generation and
+ validation failures propagate.
+
+ ## Usage
+
+ Use the owning workflow's harness command for normal work. This utility has no
+ harness command or bulk-refresh registration. For direct debugging:
+
```bash
- conda run -n sictic-env python -m skills.ranking --target persons --objective "Looking for someone with deep expertise in B2B SaaS sales" --top_k 8
+ conda run -n sictic-env python -m skills.ranking --target persons --objective "Expertise in B2B SaaS sales" --top-k 16
```
+
+ ## References
+
+ - [Person adapters](ranking_persons.py)
+ - [Tournament and ID review](ranking_top_k.py), [rationale generation](ranking_rationale.py)
+ - [Shared contracts](../standards_and_architecture/SKILL.md#ranking-workflows)