fix(v2): demote GitHub-derived props to org units + RCP_TOKEN round-robin

Two independent fixes bundled per the live debugging session.

1. **`demote_github_props_to_units` stage** addressing
   Imaging-Plaza/git-metadata-extractor issues #29 and #33:

   When an Organization had both a ROR identifier (the legal entity)
   and a GitHub presence linked via `org:hasUnit → github_url`, the
   rule-based agent stamped the GitHub-derived properties
   (`pulse:githubOrgFollowers`, `pulse:githubOrganizationHandle`) on
   the ROR parent rather than the unit. Real-world example from the
   audit: `ror.org/0070nx673` (Okino) was carrying followers=364 that
   actually belong to its unit `github.com/InteractiveComputerGraphics`.

   Add a post-pass stage that, only when the ROR parent's handle
   matches the github-only unit's handle (so the data really is the
   unit's), moves the follower count to the unit if the unit lacks it
   and clears the GitHub-derived properties on the parent. The match
   guard prevents stripping legitimate data when the parent is its own
   independent GitHub presence with separate units.

   Wired immediately after `infer_org_units` in the api.py orchestrator
   so the unit relationships are stamped before this pass runs.

2. **Multi-token `RCP_TOKEN` support** mirroring the existing
   `GITHUB_TOKEN` pattern. Set `RCP_TOKEN=sk-A,sk-B` and every model
   instantiation pulls the next key via `itertools.cycle` under a
   threading lock. Doubles the per-process rate-limit budget when the
   shared inference endpoint pushes back on bursty extracts.

   Independent cycles per env var name so distinct providers
   (`RCP_TOKEN`, `OPENAI_API_KEY`, ...) don't share state.

Both changes covered by inline synthetic tests (issue #29 example
demote roundtrip + round-robin sequencing + single-token passthrough).

Author: caviri

.env.example

@@ -34,7 +34,11 @@ GITHUB_TOKEN=your-github-token-here
 # and surfaces a clear error if the configured profile's env var is missing).
 # ---------------------------------------------------------------------------
 
-# EPFL RCP inference endpoint token.
+# EPFL RCP inference endpoint token. Comma-separated list of tokens is
+# supported (`sk-A,sk-B`) — model_config.py round-robins across them at
+# every model instantiation, which doubles the effective per-process
+# rate-limit budget when more than one token is provided. Same pattern
+# as `GITHUB_TOKEN`.
 RCP_TOKEN=your-rcp-token-here
 
 # OpenAI API key (only if a model profile is configured for OpenAI).

src/v1/llm/model_config.py

@@ -5,13 +5,46 @@
 Supports OpenAI, OpenRouter, OpenAI-compatible endpoints, and Ollama (local and remote).
 """
 
+import itertools
 import json
 import logging
 import os
+import threading
 from typing import Any, Dict, List
 
 logger = logging.getLogger(__name__)
 
+_API_KEY_LOCK = threading.Lock()
+_API_KEY_CYCLES: Dict[str, "itertools.cycle"] = {}
+_API_KEY_SOURCES: Dict[str, str] = {}
+
+
+def _next_api_key(env_var: str) -> str:
+    """Round-robin a single token out of a comma-separated env value.
+
+    Supports the same multi-token pattern as `GITHUB_TOKEN`
+    (`ghp_A,ghp_B,...`): set `RCP_TOKEN=sk-A,sk-B` and every LLM model
+    instantiation pulls the next key. Locked per-env-var so different
+    providers (`RCP_TOKEN`, `OPENAI_API_KEY`, ...) keep independent cycles.
+    Per-process cycle — with multiple uvicorn workers the rotation is
+    independent per worker, but the overall call volume splits roughly
+    evenly across tokens.
+    """
+    raw = os.getenv(env_var) or ""
+    if "," not in raw:
+        return raw.strip()
+    with _API_KEY_LOCK:
+        cached_source = _API_KEY_SOURCES.get(env_var)
+        if raw != cached_source or env_var not in _API_KEY_CYCLES:
+            tokens = [t.strip() for t in raw.split(",") if t.strip()]
+            if not tokens:
+                _API_KEY_CYCLES.pop(env_var, None)
+                _API_KEY_SOURCES[env_var] = raw
+                return ""
+            _API_KEY_CYCLES[env_var] = itertools.cycle(tokens)
+            _API_KEY_SOURCES[env_var] = raw
+        return next(_API_KEY_CYCLES[env_var])
+
 # Default model configurations
 MODEL_CONFIGS = {
     "run_llm_analysis": [
@@ -555,7 +588,7 @@ def create_pydantic_ai_model(config: Dict[str, Any]):
             model_name,
             provider=OpenAIProvider(
                 base_url=base_url,
-                api_key=os.getenv(api_key_env),
+                api_key=_next_api_key(api_key_env),
             ),
         )
     elif provider == "ollama":

src/v2/api.py

@@ -91,6 +91,7 @@
     compute_stats,
     guarantee_repo_author,
     infer_github_handle_parents,
+    demote_github_props_to_units,
     infer_org_units,
     infer_owners,
     promote_failed_id_entities,
@@ -1086,6 +1087,16 @@ async def extract(  # noqa: C901, PLR0911, PLR0912, PLR0913, PLR0915
     for warning in org_unit_warnings:
         _append_unique_warning(warnings, warning)
 
+    stage_started_at = perf_counter()
+    assembled_output, demote_warnings = demote_github_props_to_units(assembled_output)
+    logger.info(
+        "demote_github_props_to_units: demoted=%d in %.2fs",
+        len(demote_warnings),
+        perf_counter() - stage_started_at,
+    )
+    for warning in demote_warnings:
+        _append_unique_warning(warnings, warning)
+
     if _concept_tagging_is_enabled() and classification.detected_type.value == "repository":
         repository_context = (
             gathered_context.get("repository")

src/v2/pipeline/stages/__init__.py

@@ -41,6 +41,7 @@
     build_json_output,
 )
 from src.v2.pipeline.stages.ownership_check import (
+    demote_github_props_to_units,
     guarantee_repo_author,
     infer_github_handle_parents,
     infer_org_units,
@@ -80,6 +81,7 @@
     "compute_stats",
     "concept_tagging_is_enabled",
     "concept_tagging_resolve_backend",
+    "demote_github_props_to_units",
     "gather_context",
     "guarantee_repo_author",
     "hybrid_refiner_is_enabled",

src/v2/pipeline/stages/ownership_check.py

@@ -1269,7 +1269,121 @@ def _stamp_owner_contribution(person_id: str, repo_id: str) -> None:
     return new_reconciled, warnings
 
 
+def _strip_github_props(entity: dict[str, Any]) -> list[str]:
+    """Remove GitHub-derived properties from `entity`. Returns the keys cleared."""
+    cleared: list[str] = []
+    for key in ("pulse:githubOrgFollowers", "pulse:githubOrganizationHandle"):
+        if entity.get(key) not in (None, ""):
+            entity[key] = None
+            cleared.append(key)
+    identifiers = entity.get("identifiers")
+    if isinstance(identifiers, dict):
+        if isinstance(identifiers.get("pulse:githubOrganizationHandle"), str):
+            identifiers["pulse:githubOrganizationHandle"] = None
+            cleared.append("identifiers.pulse:githubOrganizationHandle")
+    return cleared
+
+
+def demote_github_props_to_units(
+    assembled: AssembledOutput,
+) -> tuple[AssembledOutput, list[str]]:
+    """Move `pulse:githubOrgFollowers` / `pulse:githubOrganizationHandle` off
+    ROR-id'd parents and onto the github-only unit they describe.
+
+    Fixes the data-shape bug reported in Imaging-Plaza/git-metadata-extractor
+    issue #29/#33: a ROR organization with `org:hasUnit → github_org` was
+    carrying the unit's follower count and handle on the legal entity. ROR
+    identifies a legal/research entity; GitHub-derived metrics belong on
+    the GitHub presence (the unit), not on the parent.
+
+    Trigger:
+    - Parent has a ROR id (`@id` or `pulse:ror` starts with `https://ror.org/`).
+    - Parent has at least one `org:hasUnit` child that is a github-only org
+      (`@id` starts with `https://github.com/`).
+    - The parent's `pulse:githubOrganizationHandle` matches the handle of one
+      of those children (so the parent's GitHub data really is the unit's).
+
+    Action:
+    - Strip the GitHub-derived properties from the parent (set to None).
+    - Copy the values onto the matching child only if the child is missing them
+      (never overwrite — the child is the canonical owner of these fields).
+    """
+    new_root: dict[str, Any] | None = (
+        deepcopy(assembled.root_entity)
+        if isinstance(assembled.root_entity, dict)
+        else None
+    )
+    new_related: list[Any] = [
+        deepcopy(entity) if isinstance(entity, dict) else entity
+        for entity in assembled.related_entities
+    ]
+    candidates: list[dict[str, Any]] = []
+    if new_root is not None:
+        candidates.append(new_root)
+    candidates.extend(e for e in new_related if isinstance(e, dict))
+
+    id_index: dict[str, dict[str, Any]] = {}
+    for entity in candidates:
+        if entity.get("type") != ORGANIZATION_TYPE:
+            continue
+        entity_id = entity.get("id")
+        if isinstance(entity_id, str) and entity_id:
+            id_index[entity_id] = entity
+
+    warnings: list[str] = []
+
+    for parent in candidates:
+        if parent.get("type") != ORGANIZATION_TYPE:
+            continue
+        parent_id = parent.get("id")
+        if not isinstance(parent_id, str) or not parent_id.startswith("https://ror.org/"):
+            continue
+        parent_handle = _entity_github_org_handle(parent)
+        if parent_handle is None:
+            continue
+        units = parent.get(HAS_UNIT_KEY)
+        if not isinstance(units, list) or not units:
+            continue
+        matched_child: dict[str, Any] | None = None
+        for unit_ref in units:
+            unit_id = unit_ref.get("@id") if isinstance(unit_ref, dict) else unit_ref
+            if not isinstance(unit_id, str):
+                continue
+            child = id_index.get(unit_id)
+            if child is None or not unit_id.startswith("https://github.com/"):
+                continue
+            child_handle = _entity_github_org_handle(child)
+            if child_handle is not None and child_handle == parent_handle:
+                matched_child = child
+                break
+        if matched_child is None:
+            continue
+        parent_followers = parent.get("pulse:githubOrgFollowers")
+        if isinstance(parent_followers, int) and not isinstance(
+            matched_child.get("pulse:githubOrgFollowers"), int
+        ):
+            matched_child["pulse:githubOrgFollowers"] = parent_followers
+        cleared = _strip_github_props(parent)
+        if cleared:
+            warnings.append(
+                f"Demoted GitHub-derived properties from ROR parent {parent_id} "
+                f"to unit {matched_child.get('id')} (handle '{parent_handle}'): "
+                f"{', '.join(cleared)}.",
+            )
+
+    return (
+        AssembledOutput(
+            root_entity=new_root if new_root is not None else assembled.root_entity,
+            related_entities=new_related,
+            excluded_entities=list(assembled.excluded_entities),
+            warnings=list(assembled.warnings),
+        ),
+        warnings,
+    )
+
+
 __all__ = [
+    "demote_github_props_to_units",
     "guarantee_repo_author",
     "infer_github_handle_parents",
     "infer_org_units",