breed-registry 1.0.0__tar.gz

breed_registry-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperInstance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breed_registry-1.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: breed-registry
+Version: 1.0.0
+Summary: The Breed Registry — model selection as breeding selection, from Working Animal Architecture
+Author: SuperInstance
+License: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/breed-registry
+Project-URL: Repository, https://github.com/SuperInstance/breed-registry
+Keywords: llm,model-selection,ai,working-animal-architecture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🐕 The Breed Registry
+
+> **Model selection as breeding selection.** In the working dog paradigm, choosing the right breed is the most important decision you'll make. This registry provides structured guidance on which base model to use for which task.
+
+## Why a Breed Registry?
+
+A working dog isn't a pet — it's bred for a purpose. Border collies herd. Labs retrieve. German shepherds protect. Each breed has instincts, temperaments, and physical traits honed over generations of selective breeding.
+
+Foundation models are the same. GPT-4 is a generalist — like a German shepherd that can do everything. Llama-3 is an open-lineage working dog you can train yourself. Mistral is a lean, efficient breed from European lines.
+
+**Choosing the wrong breed for the job wastes resources and produces poor results.** This registry exists to prevent that.
+
+---
+
+## What's Inside
+
+### `registry/` — Breed Assessments
+
+Each model is assessed like a dog breed at a confirmation show, but for **working aptitude** instead of conformation:
+
+| Field | Dog Analogy | Model Meaning |
+|---|---|---|
+| `lineage` | Pedigree / bloodline | Model family and training lineage |
+| `breed_group` | AKC group (Herding, Sporting, etc.) | Task category (General Purpose, Working, etc.) |
+| `temperament` | Breed temperament traits | Behavioral characteristics (careful, verbose, etc.) |
+| `working_aptitude` | Instinct tests & working trials | Task-specific capability scores (0-10) |
+| `cost_profile` | Feed & maintenance cost | API cost per token |
+| `speed_profile` | Speed/agility rating | Inference latency |
+| `trainability` | How well it takes to training | Fine-tune response quality |
+| `recommended_for` | Best-suited jobs | Tasks where this model excels |
+| `not_recommended_for` | Jobs it's wrong for | Tasks where this model struggles |
+| `fence_compatibility` | How well it respects boundaries | Conservation bytecode compliance |
+
+### `src/breed_registry/` — Python API
+
+```python
+from breed_registry import select_breed, compare_breeds, assess_aptitude
+
+# Find the best breed for a task
+recommendations = select_breed("code_generation")
+
+# Compare two breeds head-to-head
+report = compare_breeds("gpt-4", "llama-3")
+
+# Check a specific model's aptitude for a task
+score = assess_aptitude("mistral", "analysis")
+```
+
+---
+
+## Registered Breeds
+
+| Breed | Group | Cost | Speed | Best For |
+|---|---|---|---|---|
+| [GPT-4](registry/gpt-4.json) | General Purpose | High | Moderate | Complex reasoning, code generation |
+| [Claude-3](registry/claude-3.json | General Purpose | High | Moderate | Analysis, careful reasoning |
+| [Llama-3](registry/llama-3.json) | Open Lineage | Free | Fast | Local deployment, fine-tuning |
+| [GLM](registry/glm.json) | General Purpose | Low | Fast | Multilingual, efficient inference |
+| [Mistral](registry/mistral.json) | Working | Low | Fast | Efficient European-lineage tasks |
+
+---
+
+## Selection Philosophy
+
+### 1. Match the Breed to the Job
+Don't use a high-cost generalist for simple classification. Don't use a lightweight model for complex multi-step reasoning. Match instincts to tasks.
+
+### 2. Consider the Lineage
+Model families carry traits across generations. Fine-tunes inherit strengths and weaknesses. Know the pedigree before you commit.
+
+### 3. Respect the Fence
+Conservation compliance — how well a model respects guardrails and bytecode fences — is non-negotiable for production work. A model that won't respect boundaries is a liability.
+
+### 4. Trainability Matters
+Some breeds take to fine-tuning naturally. Others resist. If you need to specialize, choose a breed known for trainability.
+
+---
+
+## Adding a Breed
+
+To register a new model:
+
+1. Create `registry/<model-name>.json` following the assessment schema
+2. Add an entry to `registry/index.json`
+3. Submit a pull request
+
+Assess honestly. Overrating a model's working aptitude helps no one — least of all the teams who deploy it.
+
+---
+
+## License
+
+MIT
+
+---
+
+*Part of the [Working Animal Architecture](https://github.com/SuperInstance) — foundation models as working animals, not pets.*

breed_registry-1.0.0/README.md

@@ -0,0 +1,97 @@
+# 🐕 The Breed Registry
+
+> **Model selection as breeding selection.** In the working dog paradigm, choosing the right breed is the most important decision you'll make. This registry provides structured guidance on which base model to use for which task.
+
+## Why a Breed Registry?
+
+A working dog isn't a pet — it's bred for a purpose. Border collies herd. Labs retrieve. German shepherds protect. Each breed has instincts, temperaments, and physical traits honed over generations of selective breeding.
+
+Foundation models are the same. GPT-4 is a generalist — like a German shepherd that can do everything. Llama-3 is an open-lineage working dog you can train yourself. Mistral is a lean, efficient breed from European lines.
+
+**Choosing the wrong breed for the job wastes resources and produces poor results.** This registry exists to prevent that.
+
+---
+
+## What's Inside
+
+### `registry/` — Breed Assessments
+
+Each model is assessed like a dog breed at a confirmation show, but for **working aptitude** instead of conformation:
+
+| Field | Dog Analogy | Model Meaning |
+|---|---|---|
+| `lineage` | Pedigree / bloodline | Model family and training lineage |
+| `breed_group` | AKC group (Herding, Sporting, etc.) | Task category (General Purpose, Working, etc.) |
+| `temperament` | Breed temperament traits | Behavioral characteristics (careful, verbose, etc.) |
+| `working_aptitude` | Instinct tests & working trials | Task-specific capability scores (0-10) |
+| `cost_profile` | Feed & maintenance cost | API cost per token |
+| `speed_profile` | Speed/agility rating | Inference latency |
+| `trainability` | How well it takes to training | Fine-tune response quality |
+| `recommended_for` | Best-suited jobs | Tasks where this model excels |
+| `not_recommended_for` | Jobs it's wrong for | Tasks where this model struggles |
+| `fence_compatibility` | How well it respects boundaries | Conservation bytecode compliance |
+
+### `src/breed_registry/` — Python API
+
+```python
+from breed_registry import select_breed, compare_breeds, assess_aptitude
+
+# Find the best breed for a task
+recommendations = select_breed("code_generation")
+
+# Compare two breeds head-to-head
+report = compare_breeds("gpt-4", "llama-3")
+
+# Check a specific model's aptitude for a task
+score = assess_aptitude("mistral", "analysis")
+```
+
+---
+
+## Registered Breeds
+
+| Breed | Group | Cost | Speed | Best For |
+|---|---|---|---|---|
+| [GPT-4](registry/gpt-4.json) | General Purpose | High | Moderate | Complex reasoning, code generation |
+| [Claude-3](registry/claude-3.json | General Purpose | High | Moderate | Analysis, careful reasoning |
+| [Llama-3](registry/llama-3.json) | Open Lineage | Free | Fast | Local deployment, fine-tuning |
+| [GLM](registry/glm.json) | General Purpose | Low | Fast | Multilingual, efficient inference |
+| [Mistral](registry/mistral.json) | Working | Low | Fast | Efficient European-lineage tasks |
+
+---
+
+## Selection Philosophy
+
+### 1. Match the Breed to the Job
+Don't use a high-cost generalist for simple classification. Don't use a lightweight model for complex multi-step reasoning. Match instincts to tasks.
+
+### 2. Consider the Lineage
+Model families carry traits across generations. Fine-tunes inherit strengths and weaknesses. Know the pedigree before you commit.
+
+### 3. Respect the Fence
+Conservation compliance — how well a model respects guardrails and bytecode fences — is non-negotiable for production work. A model that won't respect boundaries is a liability.
+
+### 4. Trainability Matters
+Some breeds take to fine-tuning naturally. Others resist. If you need to specialize, choose a breed known for trainability.
+
+---
+
+## Adding a Breed
+
+To register a new model:
+
+1. Create `registry/<model-name>.json` following the assessment schema
+2. Add an entry to `registry/index.json`
+3. Submit a pull request
+
+Assess honestly. Overrating a model's working aptitude helps no one — least of all the teams who deploy it.
+
+---
+
+## License
+
+MIT
+
+---
+
+*Part of the [Working Animal Architecture](https://github.com/SuperInstance) — foundation models as working animals, not pets.*

breed_registry-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "breed-registry"
+version = "1.0.0"
+description = "The Breed Registry — model selection as breeding selection, from Working Animal Architecture"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "SuperInstance"},
+]
+keywords = ["llm", "model-selection", "ai", "working-animal-architecture"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/SuperInstance/breed-registry"
+Repository = "https://github.com/SuperInstance/breed-registry"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+]

breed_registry-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

breed_registry-1.0.0/src/breed_registry/__init__.py

@@ -0,0 +1,45 @@
+"""
+The Breed Registry — model selection as breeding selection.
+
+In the working dog paradigm, choosing the right breed is the most important
+decision. This library provides structured guidance on which base model to
+use for which task.
+
+Usage:
+    from breed_registry import select_breed, compare_breeds, assess_aptitude
+
+    # Find the best breed for a task
+    recommendations = select_breed("code_generation")
+
+    # Compare two breeds head-to-head
+    report = compare_breeds("gpt-4", "llama-3")
+
+    # Check a specific model's aptitude for a task
+    score = assess_aptitude("mistral", "analysis")
+"""
+
+from breed_registry.matcher import (
+    select_breed,
+    compare_breeds,
+    assess_aptitude,
+    list_breeds,
+    get_breed,
+)
+from breed_registry.models import (
+    ModelAssessment,
+    ComparisonReport,
+    AptitudeScore,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "select_breed",
+    "compare_breeds",
+    "assess_aptitude",
+    "list_breeds",
+    "get_breed",
+    "ModelAssessment",
+    "ComparisonReport",
+    "AptitudeScore",
+]

breed_registry-1.0.0/src/breed_registry/matcher.py

@@ -0,0 +1,233 @@
+"""
+Task-to-model matcher — the core selection engine.
+
+Given a task (e.g. "code_generation"), recommends the best model breeds
+based on their working aptitude scores.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from breed_registry.models import (
+    AptitudeScore,
+    ComparisonReport,
+    ModelAssessment,
+)
+
+# ---------------------------------------------------------------------------
+# Registry loading
+# ---------------------------------------------------------------------------
+
+_REGISTRY_DIR = Path(__file__).resolve().parent.parent.parent / "registry"
+
+
+def _load_registry(registry_dir: Optional[Path] = None) -> Dict[str, ModelAssessment]:
+    """Load all breed assessments from the registry directory."""
+    reg_dir = registry_dir or _REGISTRY_DIR
+    assessments: Dict[str, ModelAssessment] = {}
+
+    index_path = reg_dir / "index.json"
+    if not index_path.exists():
+        raise FileNotFoundError(f"Registry index not found at {index_path}")
+
+    with open(index_path) as f:
+        index = json.load(f)
+
+    for key, info in index.get("breeds", {}).items():
+        breed_file = reg_dir / info["file"]
+        if breed_file.exists():
+            with open(breed_file) as f:
+                data = json.load(f)
+            assessments[key] = ModelAssessment.from_dict(data)
+
+    return assessments
+
+
+# Lazy-loaded global registry
+_REGISTRY_CACHE: Optional[Dict[str, ModelAssessment]] = None
+
+
+def _get_registry() -> Dict[str, ModelAssessment]:
+    global _REGISTRY_CACHE
+    if _REGISTRY_CACHE is None:
+        _REGISTRY_CACHE = _load_registry()
+    return _REGISTRY_CACHE
+
+
+def _score_to_rating(score: int) -> str:
+    """Convert a numeric score (0-10) to a human-readable rating."""
+    if score >= 9:
+        return "excellent"
+    elif score >= 7:
+        return "good"
+    elif score >= 5:
+        return "fair"
+    elif score >= 3:
+        return "poor"
+    else:
+        return "unsuitable"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def list_breeds() -> List[str]:
+    """List all registered breed names."""
+    return sorted(_get_registry().keys())
+
+
+def get_breed(name: str) -> ModelAssessment:
+    """Get the full assessment for a specific breed.
+
+    Raises:
+        KeyError: if the breed is not registered.
+    """
+    registry = _get_registry()
+    if name not in registry:
+        raise KeyError(
+            f"Breed '{name}' not registered. Available: {', '.join(sorted(registry.keys()))}"
+        )
+    return registry[name]
+
+
+def select_breed(
+    task: str,
+    top_k: int = 3,
+    max_cost: Optional[str] = None,
+) -> List[ModelAssessment]:
+    """Recommend models for a given task, sorted by aptitude.
+
+    Args:
+        task: The task category (e.g. "code_generation", "analysis").
+        top_k: Maximum number of recommendations to return.
+        max_cost: Optional cost ceiling — "low" excludes moderate/high,
+                  "free" excludes everything but free models.
+
+    Returns:
+        List of ModelAssessment objects, best match first.
+    """
+    registry = _get_registry()
+    cost_order = {"free": 0, "low": 1, "moderate": 2, "high": 3}
+    cost_ceiling = cost_order.get(max_cost, 3) if max_cost else 3
+
+    scored: List[Tuple[int, ModelAssessment]] = []
+    for assessment in registry.values():
+        # Filter by cost ceiling
+        model_cost = cost_order.get(assessment.cost_profile, 3)
+        if model_cost > cost_ceiling:
+            continue
+
+        score = assessment.aptitude_for(task)
+        if score > 0:
+            scored.append((score, assessment))
+
+    scored.sort(key=lambda x: x[0], reverse=True)
+
+    return [assessment for _, assessment in scored[:top_k]]
+
+
+def compare_breeds(model_a: str, model_b: str) -> ComparisonReport:
+    """Compare two breeds head-to-head across all working aptitude dimensions.
+
+    Raises:
+        KeyError: if either model is not registered.
+    """
+    breed_a = get_breed(model_a)
+    breed_b = get_breed(model_b)
+
+    # Build task-by-task comparison
+    all_tasks = sorted(
+        set(breed_a.working_aptitude.keys()) | set(breed_b.working_aptitude.keys())
+    )
+
+    aptitude_comparison: Dict[str, Dict[str, int]] = {}
+    advantages_a: List[str] = []
+    advantages_b: List[str] = []
+    total_a = 0
+    total_b = 0
+
+    for task in all_tasks:
+        score_a = breed_a.aptitude_for(task)
+        score_b = breed_b.aptitude_for(task)
+        aptitude_comparison[task] = {model_a: score_a, model_b: score_b}
+        total_a += score_a
+        total_b += score_b
+
+        if score_a > score_b:
+            advantages_a.append(task)
+        elif score_b > score_a:
+            advantages_b.append(task)
+
+    margin = abs(total_a - total_b)
+    if total_a > total_b:
+        winner = model_a
+    elif total_b > total_a:
+        winner = model_b
+    else:
+        winner = "tie"
+
+    cost_order = {"free": 0, "low": 1, "moderate": 2, "high": 3}
+    cost_a = cost_order.get(breed_a.cost_profile, 3)
+    cost_b = cost_order.get(breed_b.cost_profile, 3)
+
+    if cost_a < cost_b:
+        cost_notes = f"{model_a} is cheaper ({breed_a.cost_profile} vs {breed_b.cost_profile})"
+    elif cost_b < cost_a:
+        cost_notes = f"{model_b} is cheaper ({breed_b.cost_profile} vs {breed_a.cost_profile})"
+    else:
+        cost_notes = f"Both are {breed_a.cost_profile} cost"
+
+    speed_order = {"fast": 0, "moderate": 1, "slow": 2}
+    speed_a = speed_order.get(breed_a.speed_profile, 2)
+    speed_b = speed_order.get(breed_b.speed_profile, 2)
+
+    if speed_a < speed_b:
+        speed_notes = f"{model_a} is faster ({breed_a.speed_profile} vs {breed_b.speed_profile})"
+    elif speed_b < speed_a:
+        speed_notes = f"{model_b} is faster ({breed_b.speed_profile} vs {breed_a.speed_profile})"
+    else:
+        speed_notes = f"Both are {breed_a.speed_profile} speed"
+
+    return ComparisonReport(
+        model_a=model_a,
+        model_b=model_b,
+        aptitude_comparison=aptitude_comparison,
+        winner=winner,
+        margin=margin,
+        advantages_a=advantages_a,
+        advantages_b=advantages_b,
+        cost_notes=cost_notes,
+        speed_notes=speed_notes,
+    )
+
+
+def assess_aptitude(model: str, task: str) -> AptitudeScore:
+    """Assess a specific model's aptitude for a specific task.
+
+    Raises:
+        KeyError: if the model is not registered.
+    """
+    breed = get_breed(model)
+    score = breed.aptitude_for(task)
+
+    # Calculate percentile
+    registry = _get_registry()
+    all_scores = [a.aptitude_for(task) for a in registry.values() if a.aptitude_for(task) > 0]
+    if all_scores:
+        below = sum(1 for s in all_scores if s < score)
+        percentile = round((below / len(all_scores)) * 100, 1)
+    else:
+        percentile = None
+
+    return AptitudeScore(
+        model=model,
+        task=task,
+        score=score,
+        rating=_score_to_rating(score),
+        percentile=percentile,
+    )

breed_registry-1.0.0/src/breed_registry/models.py

@@ -0,0 +1,94 @@
+"""
+Data models for the Breed Registry.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class AptitudeScore:
+    """A model's aptitude score for a specific task."""
+
+    model: str
+    task: str
+    score: int  # 0-10
+    rating: str  # human-readable rating
+    percentile: Optional[float] = None  # percentile among all assessed models
+
+    def __repr__(self) -> str:
+        return f"AptitudeScore(model={self.model!r}, task={self.task!r}, score={self.score}/10, rating={self.rating!r})"
+
+
+@dataclass
+class ComparisonReport:
+    """Head-to-head comparison between two models."""
+
+    model_a: str
+    model_b: str
+    aptitude_comparison: Dict[str, Dict[str, int]]  # task -> {model_a: score, model_b: score}
+    winner: str  # overall winner
+    margin: int  # total score difference
+    advantages_a: List[str]  # tasks where model_a wins
+    advantages_b: List[str]  # tasks where model_b wins
+    cost_notes: str
+    speed_notes: str
+
+    def summary(self) -> str:
+        lines = [
+            f"Comparison: {self.model_a} vs {self.model_b}",
+            f"Overall winner: {self.winner} (margin: {self.margin} points)",
+            "",
+            f"Advantages {self.model_a}: {', '.join(self.advantages_a) or 'none'}",
+            f"Advantages {self.model_b}: {', '.join(self.advantages_b) or 'none'}",
+            "",
+            f"Cost: {self.cost_notes}",
+            f"Speed: {self.speed_notes}",
+        ]
+        return "\n".join(lines)
+
+
+@dataclass
+class ModelAssessment:
+    """Full breed assessment for a model."""
+
+    name: str
+    lineage: str
+    breed_group: str
+    temperament: List[str]
+    working_aptitude: Dict[str, int]
+    cost_profile: str
+    speed_profile: str
+    trainability: str
+    recommended_for: List[str]
+    not_recommended_for: List[str]
+    fence_compatibility: str
+    notes: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ModelAssessment":
+        return cls(
+            name=data["name"],
+            lineage=data["lineage"],
+            breed_group=data["breed_group"],
+            temperament=data["temperament"],
+            working_aptitude=data["working_aptitude"],
+            cost_profile=data["cost_profile"],
+            speed_profile=data["speed_profile"],
+            trainability=data["trainability"],
+            recommended_for=data["recommended_for"],
+            not_recommended_for=data["not_recommended_for"],
+            fence_compatibility=data["fence_compatibility"],
+            notes=data.get("notes"),
+        )
+
+    def aptitude_for(self, task: str) -> int:
+        """Return the aptitude score (0-10) for a given task."""
+        return self.working_aptitude.get(task, 0)
+
+    def overall_score(self) -> float:
+        """Average aptitude across all assessed tasks."""
+        scores = list(self.working_aptitude.values())
+        return sum(scores) / len(scores) if scores else 0.0

breed_registry-1.0.0/src/breed_registry.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: breed-registry
+Version: 1.0.0
+Summary: The Breed Registry — model selection as breeding selection, from Working Animal Architecture
+Author: SuperInstance
+License: MIT
+Project-URL: Homepage, https://github.com/SuperInstance/breed-registry
+Project-URL: Repository, https://github.com/SuperInstance/breed-registry
+Keywords: llm,model-selection,ai,working-animal-architecture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🐕 The Breed Registry
+
+> **Model selection as breeding selection.** In the working dog paradigm, choosing the right breed is the most important decision you'll make. This registry provides structured guidance on which base model to use for which task.
+
+## Why a Breed Registry?
+
+A working dog isn't a pet — it's bred for a purpose. Border collies herd. Labs retrieve. German shepherds protect. Each breed has instincts, temperaments, and physical traits honed over generations of selective breeding.
+
+Foundation models are the same. GPT-4 is a generalist — like a German shepherd that can do everything. Llama-3 is an open-lineage working dog you can train yourself. Mistral is a lean, efficient breed from European lines.
+
+**Choosing the wrong breed for the job wastes resources and produces poor results.** This registry exists to prevent that.
+
+---
+
+## What's Inside
+
+### `registry/` — Breed Assessments
+
+Each model is assessed like a dog breed at a confirmation show, but for **working aptitude** instead of conformation:
+
+| Field | Dog Analogy | Model Meaning |
+|---|---|---|
+| `lineage` | Pedigree / bloodline | Model family and training lineage |
+| `breed_group` | AKC group (Herding, Sporting, etc.) | Task category (General Purpose, Working, etc.) |
+| `temperament` | Breed temperament traits | Behavioral characteristics (careful, verbose, etc.) |
+| `working_aptitude` | Instinct tests & working trials | Task-specific capability scores (0-10) |
+| `cost_profile` | Feed & maintenance cost | API cost per token |
+| `speed_profile` | Speed/agility rating | Inference latency |
+| `trainability` | How well it takes to training | Fine-tune response quality |
+| `recommended_for` | Best-suited jobs | Tasks where this model excels |
+| `not_recommended_for` | Jobs it's wrong for | Tasks where this model struggles |
+| `fence_compatibility` | How well it respects boundaries | Conservation bytecode compliance |
+
+### `src/breed_registry/` — Python API
+
+```python
+from breed_registry import select_breed, compare_breeds, assess_aptitude
+
+# Find the best breed for a task
+recommendations = select_breed("code_generation")
+
+# Compare two breeds head-to-head
+report = compare_breeds("gpt-4", "llama-3")
+
+# Check a specific model's aptitude for a task
+score = assess_aptitude("mistral", "analysis")
+```
+
+---
+
+## Registered Breeds
+
+| Breed | Group | Cost | Speed | Best For |
+|---|---|---|---|---|
+| [GPT-4](registry/gpt-4.json) | General Purpose | High | Moderate | Complex reasoning, code generation |
+| [Claude-3](registry/claude-3.json | General Purpose | High | Moderate | Analysis, careful reasoning |
+| [Llama-3](registry/llama-3.json) | Open Lineage | Free | Fast | Local deployment, fine-tuning |
+| [GLM](registry/glm.json) | General Purpose | Low | Fast | Multilingual, efficient inference |
+| [Mistral](registry/mistral.json) | Working | Low | Fast | Efficient European-lineage tasks |
+
+---
+
+## Selection Philosophy
+
+### 1. Match the Breed to the Job
+Don't use a high-cost generalist for simple classification. Don't use a lightweight model for complex multi-step reasoning. Match instincts to tasks.
+
+### 2. Consider the Lineage
+Model families carry traits across generations. Fine-tunes inherit strengths and weaknesses. Know the pedigree before you commit.
+
+### 3. Respect the Fence
+Conservation compliance — how well a model respects guardrails and bytecode fences — is non-negotiable for production work. A model that won't respect boundaries is a liability.
+
+### 4. Trainability Matters
+Some breeds take to fine-tuning naturally. Others resist. If you need to specialize, choose a breed known for trainability.
+
+---
+
+## Adding a Breed
+
+To register a new model:
+
+1. Create `registry/<model-name>.json` following the assessment schema
+2. Add an entry to `registry/index.json`
+3. Submit a pull request
+
+Assess honestly. Overrating a model's working aptitude helps no one — least of all the teams who deploy it.
+
+---
+
+## License
+
+MIT
+
+---
+
+*Part of the [Working Animal Architecture](https://github.com/SuperInstance) — foundation models as working animals, not pets.*

breed_registry-1.0.0/src/breed_registry.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/breed_registry/__init__.py
+src/breed_registry/matcher.py
+src/breed_registry/models.py
+src/breed_registry.egg-info/PKG-INFO
+src/breed_registry.egg-info/SOURCES.txt
+src/breed_registry.egg-info/dependency_links.txt
+src/breed_registry.egg-info/top_level.txt
+tests/test_matcher.py

breed_registry-1.0.0/src/breed_registry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

breed_registry-1.0.0/src/breed_registry.egg-info/top_level.txt

@@ -0,0 +1 @@
+breed_registry

breed_registry-1.0.0/tests/test_matcher.py

@@ -0,0 +1,212 @@
+"""
+Tests for the Breed Registry matcher.
+"""
+
+import pytest
+
+from breed_registry import (
+    select_breed,
+    compare_breeds,
+    assess_aptitude,
+    list_breeds,
+    get_breed,
+)
+from breed_registry.models import AptitudeScore, ComparisonReport, ModelAssessment
+
+
+# ---------------------------------------------------------------------------
+# Registry tests
+# ---------------------------------------------------------------------------
+
+class TestListBreeds:
+    def test_returns_all_registered_breeds(self):
+        breeds = list_breeds()
+        assert "gpt-4" in breeds
+        assert "claude-3" in breeds
+        assert "llama-3" in breeds
+        assert "glm" in breeds
+        assert "mistral" in breeds
+
+    def test_returns_sorted(self):
+        breeds = list_breeds()
+        assert breeds == sorted(breeds)
+
+
+class TestGetBreed:
+    def test_returns_assessment(self):
+        assessment = get_breed("gpt-4")
+        assert assessment.name == "gpt-4"
+        assert assessment.breed_group == "General Purpose"
+        assert "code_generation" in assessment.working_aptitude
+
+    def test_raises_for_unknown_breed(self):
+        with pytest.raises(KeyError, match="not registered"):
+            get_breed("nonexistent-model")
+
+    def test_assessment_has_all_fields(self):
+        assessment = get_breed("claude-3")
+        assert assessment.lineage
+        assert assessment.temperament
+        assert assessment.cost_profile
+        assert assessment.speed_profile
+        assert assessment.trainability
+        assert assessment.recommended_for
+        assert assessment.not_recommended_for
+        assert assessment.fence_compatibility
+
+
+# ---------------------------------------------------------------------------
+# select_breed tests
+# ---------------------------------------------------------------------------
+
+class TestSelectBreed:
+    def test_returns_recommendations(self):
+        recommendations = select_breed("code_generation")
+        assert len(recommendations) > 0
+        assert all(isinstance(r, ModelAssessment) for r in recommendations)
+
+    def test_sorted_by_aptitude(self):
+        recommendations = select_breed("analysis", top_k=5)
+        scores = [r.aptitude_for("analysis") for r in recommendations]
+        assert scores == sorted(scores, reverse=True)
+
+    def test_respects_top_k(self):
+        recommendations = select_breed("code_generation", top_k=2)
+        assert len(recommendations) <= 2
+
+    def test_gpt4_top_for_code_generation(self):
+        recommendations = select_breed("code_generation", top_k=1)
+        assert recommendations[0].name == "gpt-4"
+
+    def test_claude3_top_for_analysis(self):
+        recommendations = select_breed("analysis", top_k=1)
+        assert recommendations[0].name == "claude-3"
+
+    def test_cost_filter_free(self):
+        recommendations = select_breed("code_generation", max_cost="free")
+        for r in recommendations:
+            assert r.cost_profile == "free"
+
+    def test_cost_filter_low(self):
+        recommendations = select_breed("code_generation", max_cost="low")
+        for r in recommendations:
+            assert r.cost_profile in ("free", "low")
+
+    def test_unknown_task_returns_empty(self):
+        recommendations = select_breed("nonexistent_task")
+        assert len(recommendations) == 0
+
+
+# ---------------------------------------------------------------------------
+# compare_breeds tests
+# ---------------------------------------------------------------------------
+
+class TestCompareBreeds:
+    def test_returns_comparison_report(self):
+        report = compare_breeds("gpt-4", "llama-3")
+        assert isinstance(report, ComparisonReport)
+        assert report.model_a == "gpt-4"
+        assert report.model_b == "llama-3"
+
+    def test_comparison_has_all_tasks(self):
+        report = compare_breeds("gpt-4", "claude-3")
+        breed_a = get_breed("gpt-4")
+        breed_b = get_breed("claude-3")
+        all_tasks = set(breed_a.working_aptitude.keys()) | set(breed_b.working_aptitude.keys())
+        assert set(report.aptitude_comparison.keys()) == all_tasks
+
+    def test_winner_is_determined(self):
+        report = compare_breeds("gpt-4", "llama-3")
+        assert report.winner in ("gpt-4", "llama-3", "tie")
+        assert report.margin >= 0
+
+    def test_gpt4_vs_llama3_gpt4_wins(self):
+        report = compare_breeds("gpt-4", "llama-3")
+        assert report.winner == "gpt-4"
+
+    def test_advantages_populated(self):
+        report = compare_breeds("gpt-4", "llama-3")
+        # GPT-4 should have advantages in at least some tasks
+        assert len(report.advantages_a) > 0 or len(report.advantages_b) > 0
+
+    def test_summary_method_works(self):
+        report = compare_breeds("gpt-4", "claude-3")
+        summary = report.summary()
+        assert "gpt-4" in summary
+        assert "claude-3" in summary
+        assert "winner" in summary.lower()
+
+    def test_raises_for_unknown_model(self):
+        with pytest.raises(KeyError):
+            compare_breeds("gpt-4", "nonexistent")
+
+
+# ---------------------------------------------------------------------------
+# assess_aptitude tests
+# ---------------------------------------------------------------------------
+
+class TestAssessAptitude:
+    def test_returns_aptitude_score(self):
+        score = assess_aptitude("mistral", "analysis")
+        assert isinstance(score, AptitudeScore)
+        assert score.model == "mistral"
+        assert score.task == "analysis"
+        assert 0 <= score.score <= 10
+
+    def test_rating_matches_score(self):
+        score = assess_aptitude("gpt-4", "code_generation")
+        assert score.score == 9
+        assert score.rating == "excellent"
+
+    def test_percentile_calculated(self):
+        score = assess_aptitude("gpt-4", "code_generation")
+        assert score.percentile is not None
+        assert 0.0 <= score.percentile <= 100.0
+
+    def test_claude3_perfect_analysis(self):
+        score = assess_aptitude("claude-3", "analysis")
+        assert score.score == 10
+
+    def test_raises_for_unknown_model(self):
+        with pytest.raises(KeyError):
+            assess_aptitude("nonexistent", "code_generation")
+
+
+# ---------------------------------------------------------------------------
+# ModelAssessment unit tests
+# ---------------------------------------------------------------------------
+
+class TestModelAssessment:
+    def test_overall_score(self):
+        assessment = get_breed("gpt-4")
+        overall = assessment.overall_score()
+        assert overall > 0
+        assert overall <= 10
+
+    def test_aptitude_for_known_task(self):
+        assessment = get_breed("gpt-4")
+        assert assessment.aptitude_for("code_generation") == 9
+
+    def test_aptitude_for_unknown_task(self):
+        assessment = get_breed("gpt-4")
+        assert assessment.aptitude_for("nonexistent") == 0
+
+    def test_from_dict_roundtrip(self):
+        original = get_breed("gpt-4")
+        data = {
+            "name": original.name,
+            "lineage": original.lineage,
+            "breed_group": original.breed_group,
+            "temperament": original.temperament,
+            "working_aptitude": original.working_aptitude,
+            "cost_profile": original.cost_profile,
+            "speed_profile": original.speed_profile,
+            "trainability": original.trainability,
+            "recommended_for": original.recommended_for,
+            "not_recommended_for": original.not_recommended_for,
+            "fence_compatibility": original.fence_compatibility,
+            "notes": original.notes,
+        }
+        rebuilt = ModelAssessment.from_dict(data)
+        assert rebuilt.name == original.name
+        assert rebuilt.overall_score() == original.overall_score()