{
  "pack_id": "hackathon-ecosystem-index",
  "title": "Hackathon ecosystem index",
  "version": "0.1.0",
  "summary": "A collection of nouns and verbs for decomposing public AI repository metadata and READMEs into searchable Task (verb) and Task Object (noun) signatures and serving hybrid Okapi BM25 plus facet and stack Reciprocal Rank Fusion (k=60) retrieval.",
  "dependencies": [
    "tool-discovery"
  ],
  "boundaries": [
    "Every decomposed task signature is marked candidate_unverified with explicit scan provenance; README prose never proves runtime behavior.",
    "Indexing reads static metadata and README summaries without executing third-party repository code.",
    "Importing the pack writes nothing, enqueues nothing and installs no code."
  ],
  "nouns": [
    {
      "slug": "pack",
      "category": "noun.skill_pack",
      "role": "pack",
      "title": "A collection of nouns and verbs for decomposing public AI repository metadata and READMEs into searchable Task and Task Object signatures",
      "value": {
        "lets_workers": "Ingest public AI repository metadata and READMEs, decompose entrypoints and artifacts into candidate_unverified Task (verb) and Task Object (noun) records with explicit provenance, and serve hybrid Okapi BM25 plus stack and domain Reciprocal Rank Fusion (k=60) queries.",
        "flow": [
          {
            "verb": {
              "$verb": "hackathon-ecosystem-index.decompose-repo-catalog"
            },
            "when": "Map repository scan rows and READMEs into Task and Task-Object records."
          },
          {
            "verb": {
              "$verb": "hackathon-ecosystem-index.verify-catalog-hygiene"
            },
            "when": "Verify provenance tags, candidate_unverified labels and em-dash-free summaries."
          },
          {
            "verb": {
              "$verb": "hackathon-ecosystem-index.search-ecosystem-rrf"
            },
            "when": "Rank repositories with BM25 + facet Reciprocal Rank Fusion (k=60)."
          }
        ],
        "guardrails": [
          {
            "$pin": "guardrail.candidate-unverified-only"
          },
          {
            "$pin": "guardrail.static-metadata-no-exec"
          }
        ],
        "tool": {
          "$pin": "tool.ecosystem-index"
        },
        "worked_example": "Synthetic 4-repository catalog recomputed in test_ecosystem_index.py: decomposes CLI commands, MCP tools and model stack facets into candidate_unverified Tasks and Task Objects and ranks synth-lab/sam-frame-guard first (RRF = 0.032787 at k=60) for a SAM video mask query."
      },
      "relations": [
        [
          "requires_noun",
          "guardrail.candidate-unverified-only"
        ],
        [
          "requires_noun",
          "guardrail.static-metadata-no-exec"
        ],
        [
          "requires_noun",
          "spec.decomposition-and-rrf"
        ],
        [
          "requires_noun",
          "tool.ecosystem-index"
        ],
        [
          "requires_noun",
          "template.catalog-record"
        ],
        [
          "requires_noun",
          "template.search-response"
        ]
      ]
    },
    {
      "slug": "guardrail.candidate-unverified-only",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: every decomposed repository task stays candidate_unverified with scan provenance",
      "category_reason": "Prevents directory listings or README claims from being mistaken for verified tools.",
      "value": {
        "rule": "Decomposed tasks always carry verification_status: candidate_unverified and provenance: public_repo_metadata_scan_2026_10_30 until separately sandbox-tested and reviewed.",
        "how_it_is_checked": "decompose_repository stamps candidate_unverified on every emitted task and PROVENANCE_TAG on every record."
      }
    },
    {
      "slug": "guardrail.static-metadata-no-exec",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: decompose repositories from static manifests and READMEs without running untrusted code",
      "category_reason": "Protects workers from arbitrary code execution while indexing public repositories.",
      "value": {
        "rule": "Catalog decomposition parses pre-collected file manifests, AST/CLI entrypoint tables and README text only; it never runs setup scripts, containers or build hooks from indexed repositories.",
        "how_it_is_checked": "ecosystem_index imports only Python standard-library text, math and JSON modules."
      }
    },
    {
      "slug": "spec.decomposition-and-rrf",
      "category": "noun.benchmark_suite",
      "role": "spec",
      "title": "Specification: Task and Task-Object category mapping and BM25 + RRF (k=60) retrieval",
      "category_reason": "Defines deterministic taxonomy mapping and hybrid ranking hyperparameters.",
      "value": {
        "bm25": {
          "k1": 1.5,
          "b": 0.75
        },
        "rrf": {
          "k": 60,
          "formula": "sum(1 / (60 + rank_i))"
        },
        "provenance_tag": "public_repo_metadata_scan_2026_10_30",
        "verb_mapping": {
          "build": "verb.compile_dag",
          "run_serve": "verb.solve_draft",
          "test_check": "verb.verify_gate",
          "data_processing": "verb.ingest",
          "agent_tool": "verb.probe_source",
          "scheduled": "verb.fetch_feed"
        },
        "noun_mapping": {
          "docs": "noun.public_source",
          "code": "noun.code_node",
          "tool": "noun.mcp_server",
          "model": "noun.model_spec",
          "prompt": "noun.prompt_shim",
          "dataset": "noun.feed_source",
          "asset": "noun.scene_recipe",
          "config": "noun.shim_provision",
          "test_evaluation": "noun.eval_run"
        }
      }
    },
    {
      "slug": "tool.ecosystem-index",
      "category": "noun.code_node",
      "role": "tool_card",
      "title": "Tool card: repository Task/Task-Object decomposer and BM25 + RRF (k=60) search engine",
      "category_reason": "Tested Python standard-library package pinned by path, file count and digest.",
      "value": {
        "name": "hackathon ecosystem index",
        "code": {
          "$code": "hackathon-ecosystem-index"
        },
        "runtime": "Python 3.10 or later, standard library only.",
        "commands": [
          "python -m ecosystem_index decompose --input RAW_SCANS.json [--out CATALOG.json]",
          "python -m ecosystem_index search --catalog CATALOG.json --query TEXT [--stack sam llama] [--domain Vision]"
        ],
        "does": [
          "Decomposes public repository metadata and README paragraphs into candidate_unverified Tasks and Task Objects.",
          "Builds an Okapi BM25 index (k1=1.5, b=0.75) and fuses lexical and stack/domain facet rankings via Reciprocal Rank Fusion (k=60)."
        ],
        "does_not": [
          "Clone or execute third-party code, call external APIs, or endorse unreviewed repositories."
        ],
        "code_license": "MIT"
      },
      "relations": [
        [
          "verifies",
          "spec.decomposition-and-rrf"
        ]
      ]
    },
    {
      "slug": "template.catalog-record",
      "category": "noun.scene_recipe",
      "role": "template",
      "title": "Template: decomposed public repository Task and Task-Object catalog record",
      "value": {
        "describes": "a single public repository decomposed into candidate_unverified Tasks, Task Objects, stack tags and provenance",
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "repo",
            "url",
            "project_track",
            "project_domain",
            "meta_stack",
            "tasks",
            "task_objects",
            "summary",
            "provenance"
          ],
          "properties": {
            "repo": {
              "type": "string",
              "minLength": 3
            },
            "url": {
              "type": "string",
              "pattern": "^https://"
            },
            "project_track": {
              "type": "string",
              "minLength": 1
            },
            "project_domain": {
              "type": "string",
              "minLength": 1
            },
            "meta_stack": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "tasks": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object"
              }
            },
            "task_objects": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "object"
              }
            },
            "summary": {
              "type": "string",
              "minLength": 1
            },
            "provenance": {
              "type": "string",
              "const": "public_repo_metadata_scan_2026_10_30"
            }
          }
        },
        "example": {
          "repo": "synth-lab/sam-frame-guard",
          "url": "https://github.com/synth-lab/sam-frame-guard",
          "project_track": "Track 2",
          "project_domain": "Multimodal Vision & Video (SAM)",
          "meta_stack": [
            "sam",
            "spark",
            "weights"
          ],
          "tasks": [
            {
              "task_id": "task.check-masks",
              "verb_category": "verb.verify_gate",
              "source_category": "test_check",
              "surface_kind": "cli_command",
              "name": "check-masks",
              "verification_status": "candidate_unverified"
            },
            {
              "task_id": "task.segment-ui",
              "verb_category": "verb.probe_source",
              "source_category": "agent_tool",
              "surface_kind": "mcp_tool",
              "name": "segment_ui",
              "verification_status": "candidate_unverified"
            }
          ],
          "task_objects": [
            {
              "object_id": "object.code",
              "noun_category": "noun.code_node",
              "source_facet": "code",
              "count": 14
            },
            {
              "object_id": "object.model",
              "noun_category": "noun.model_spec",
              "source_facet": "model",
              "count": 1
            },
            {
              "object_id": "object.test_evaluation",
              "noun_category": "noun.eval_run",
              "source_facet": "test_evaluation",
              "count": 5
            },
            {
              "object_id": "object.tool",
              "noun_category": "noun.mcp_server",
              "source_facet": "tool",
              "count": 2
            },
            {
              "object_id": "object.stack-sam",
              "noun_category": "noun.model_spec",
              "source_facet": "meta_stack:sam",
              "count": 1
            },
            {
              "object_id": "object.stack-spark",
              "noun_category": "noun.model_spec",
              "source_facet": "meta_stack:spark",
              "count": 1
            },
            {
              "object_id": "object.stack-weights",
              "noun_category": "noun.model_spec",
              "source_facet": "meta_stack:weights",
              "count": 1
            }
          ],
          "summary": "Segment UI regions in video frames with SAM masks and check caption collisions.",
          "provenance": "public_repo_metadata_scan_2026_10_30"
        }
      }
    },
    {
      "slug": "template.search-response",
      "category": "noun.scene_recipe",
      "role": "template",
      "title": "Template: hybrid BM25 + facet Reciprocal Rank Fusion (k=60) search response",
      "value": {
        "describes": "ranked repository identifiers and top RRF score for a hybrid ecosystem query",
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "rrf_k",
            "ranked_repos",
            "top_rrf_score"
          ],
          "properties": {
            "rrf_k": {
              "type": "integer",
              "const": 60
            },
            "ranked_repos": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string"
              }
            },
            "top_rrf_score": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          }
        },
        "example": {
          "rrf_k": 60,
          "ranked_repos": [
            "synth-lab/sam-frame-guard",
            "synth-lab/glimmer-caption-sync",
            "synth-lab/offline-lora-bench"
          ],
          "top_rrf_score": 0.032787
        }
      }
    },
    {
      "slug": "example.raw-repo-scans",
      "category": "noun.eval_run",
      "role": "example",
      "synthetic": true,
      "title": "Worked example input: synthetic 4-repository metadata scan and hybrid search query",
      "category_reason": "Synthetic scan inputs recomputed by test_ecosystem_index.py.",
      "value": {
        "repositories": [
          {
            "repo": "synth-lab/sam-frame-guard",
            "track": "Track 2",
            "domain": "Multimodal Vision & Video (SAM)",
            "meta_stack": [
              "sam",
              "weights",
              "spark"
            ],
            "primary_language": "Python",
            "license": "MIT",
            "scan_status": "ok",
            "head_sha": "1111111111111111111111111111111111111111",
            "tests_present": true,
            "mcp_adopted": true,
            "readme_first_paragraph": "Segment UI regions in video frames with SAM masks and check caption collisions.",
            "verb_items": [
              {
                "category": "test_check",
                "kind": "cli_command",
                "name": "check-masks"
              },
              {
                "category": "agent_tool",
                "kind": "mcp_tool",
                "name": "segment_ui"
              }
            ],
            "noun_counts": {
              "code": 14,
              "tool": 2,
              "model": 1,
              "test_evaluation": 5
            }
          },
          {
            "repo": "synth-lab/llama-mcp-router",
            "track": "Track 2",
            "domain": "Developer Tooling, Infra & Security",
            "meta_stack": [
              "llama",
              "meta_api",
              "code"
            ],
            "primary_language": "TypeScript",
            "license": "Apache-2.0",
            "scan_status": "ok",
            "head_sha": "2222222222222222222222222222222222222222",
            "tests_present": true,
            "mcp_adopted": true,
            "readme_first_paragraph": "Schema-validated MCP tool router and token budget profiler for Llama agents.",
            "verb_items": [
              {
                "category": "agent_tool",
                "kind": "mcp_tool",
                "name": "route_call"
              },
              {
                "category": "test_check",
                "kind": "npm_script",
                "name": "test"
              }
            ],
            "noun_counts": {
              "code": 19,
              "tool": 4,
              "config": 3,
              "test_evaluation": 6
            }
          },
          {
            "repo": "synth-lab/glimmer-caption-sync",
            "track": "Track 1",
            "domain": "Creative Media & Audio",
            "meta_stack": [
              "glimmer",
              "spark"
            ],
            "primary_language": "Python",
            "license": "MIT",
            "scan_status": "ok",
            "head_sha": "3333333333333333333333333333333333333333",
            "tests_present": true,
            "mcp_adopted": false,
            "readme_first_paragraph": "Align WebVTT narration cues to voiced audio phrases and flag pause bleed.",
            "verb_items": [
              {
                "category": "data_processing",
                "kind": "cli_command",
                "name": "align-vtt"
              }
            ],
            "noun_counts": {
              "code": 7,
              "asset": 3,
              "test_evaluation": 2
            }
          },
          {
            "repo": "synth-lab/offline-lora-bench",
            "track": "Track 2",
            "domain": "Model Adaptation & Evaluation",
            "meta_stack": [
              "llama",
              "weights"
            ],
            "primary_language": "Python",
            "license": "MIT",
            "scan_status": "metadata_only",
            "head_sha": "",
            "tests_present": false,
            "mcp_adopted": false,
            "readme_first_paragraph": "Evaluate LoRA adapters against holdout bootstrap confidence intervals.",
            "verb_items": [],
            "noun_counts": {
              "docs": 1,
              "model": 1
            }
          }
        ],
        "search_query": {
          "query": "video frame mask caption collisions",
          "preferred_stack": [
            "sam",
            "weights"
          ],
          "preferred_domain": "Vision"
        }
      }
    },
    {
      "slug": "example.search-results",
      "category": "noun.eval_run",
      "role": "example",
      "synthetic": true,
      "title": "Worked example output: recomputed RRF (k=60) ranked repositories",
      "category_reason": "Deterministic hybrid search output conforming to template.search-response.",
      "value": {
        "conforms_to": {
          "$pin": "template.search-response"
        },
        "instance": {
          "rrf_k": 60,
          "ranked_repos": [
            "synth-lab/sam-frame-guard",
            "synth-lab/glimmer-caption-sync",
            "synth-lab/offline-lora-bench"
          ],
          "top_rrf_score": 0.032787
        }
      },
      "relations": [
        [
          "derives_from",
          "example.raw-repo-scans"
        ],
        [
          "verifies",
          "template.search-response"
        ]
      ]
    }
  ],
  "verbs": [
    {
      "slug": "decompose-repo-catalog",
      "kind": "verb.ingest",
      "title": "Decompose public repository metadata and READMEs into Tasks and Task Objects",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Transform static repository metadata, entrypoint counts and README summaries into searchable Task and Task-Object records stamped candidate_unverified.",
      "outcome": "Decomposed repository catalog records with explicit provenance.",
      "ready_outcome": "catalog_decomposed",
      "pinned": [
        "spec.decomposition-and-rrf",
        "tool.ecosystem-index",
        "guardrail.candidate-unverified-only",
        "guardrail.static-metadata-no-exec"
      ],
      "slots": [
        {
          "name": "raw_repo_scans",
          "category": "noun.public_source",
          "description": "Pin of static repository scan metadata."
        }
      ],
      "network": [
        "local_only",
        "Processes pre-collected metadata files locally without network calls."
      ],
      "produces": [
        {
          "name": "decomposed_catalog",
          "template": "template.catalog-record"
        }
      ],
      "steps": [
        "Run python -m ecosystem_index decompose on the input repository metadata JSON.",
        "Ensure every task carries verification_status: candidate_unverified and provenance: public_repo_metadata_scan_2026_10_30."
      ],
      "acceptance": [
        {
          "id": "every-row-stamped",
          "check": "Every emitted record has non-empty tasks, task_objects and provenance == public_repo_metadata_scan_2026_10_30.",
          "method": "deterministic"
        }
      ]
    },
    {
      "slug": "verify-catalog-hygiene",
      "kind": "verb.verify_gate",
      "title": "Verify provenance, schema conformance and unverified labels across a catalog",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Check every catalog record for unique repository identifiers, absence of em-dashes, valid Tessera noun/verb categories and honest candidate_unverified status.",
      "outcome": "A catalog hygiene receipt recording row counts and SHA-256 digest.",
      "ready_outcome": "catalog_hygiene_verified",
      "pinned": [
        "template.catalog-record",
        "guardrail.candidate-unverified-only"
      ],
      "slots": [
        {
          "name": "decomposed_catalog",
          "category": "noun.feed_source",
          "description": "Pin of the decomposed ecosystem catalog."
        }
      ],
      "produces": [
        {
          "name": "hygiene_receipt",
          "template": "template.search-response"
        }
      ],
      "steps": [
        "Check every row's tasks and task_objects categories against spec.decomposition-and-rrf.",
        "Verify zero em-dashes and compute the canonical SHA-256 of the project array."
      ],
      "acceptance": [
        {
          "id": "zero-verified-claims",
          "check": "No task claims verified status without an external sandbox evaluation.",
          "method": "deterministic"
        }
      ],
      "follows": [
        "hackathon-ecosystem-index.decompose-repo-catalog"
      ]
    },
    {
      "slug": "search-ecosystem-rrf",
      "kind": "verb.situate",
      "title": "Search decomposed repositories with hybrid BM25 and facet RRF (k=60)",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Index decomposed repositories with Okapi BM25, score stack, domain, track and task-category facets, and fuse both rankings with Reciprocal Rank Fusion (k=60).",
      "outcome": "Top-k ranked repositories with RRF, BM25 and facet scores.",
      "ready_outcome": "ecosystem_searched",
      "pinned": [
        "spec.decomposition-and-rrf",
        "tool.ecosystem-index",
        "template.search-response"
      ],
      "slots": [
        {
          "name": "decomposed_catalog",
          "category": "noun.feed_source",
          "description": "Pin of the verified ecosystem catalog."
        }
      ],
      "produces": [
        {
          "name": "search_results",
          "template": "template.search-response"
        }
      ],
      "steps": [
        "Run hybrid_search with rrf_k=60 over the catalog using the query text and optional stack/domain facets.",
        "Return ranked repository IDs and validate the response against template.search-response."
      ],
      "acceptance": [
        {
          "id": "rrf-k60-exact",
          "check": "hybrid_search reproduces ranked_repos and top_rrf_score.",
          "method": "deterministic"
        }
      ],
      "follows": [
        "hackathon-ecosystem-index.verify-catalog-hygiene"
      ]
    }
  ]
}