feat(software): add unscored software category (§6.11) (#42)

* feat(software): add unscored software category (§6.11)

Adds a standalone `software` category (video game sibling — no brand FK,
makers as free-text developers/publishers). Model + schema + serializer +
router (list/detail, sort, unscored) + main + seed + dump COLLECTIONS +
validate (SOFTWARE_REQUIRED) + integration tests. Fields: release_date,
developers, publishers, operating_systems, programming_languages, licenses,
genres. Enables Wikidata Q7397 software (~14k) toward the 1M dataset.

* ci: retrigger (setup-python runner flake)

* ci(test): bump setup-python v5->v6 (fix Node 24 pip-cache stack overflow)

* ci(test): drop pip cache (Node 24 stack-overflow in setup-python cache restore)

Author: Seungpyo1007

.github/workflows/test.yml

@@ -16,10 +16,9 @@ jobs:
           repository: GetTechAPI/TechAPI
           path: TechAPI
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
-          cache: pip
 
       - name: Install dependencies
         run: pip install -e ".[dev]"

app/dump.py

@@ -32,6 +32,7 @@
     "laptops",
     "monitors",
     "games",
+    "software",
 ]
 # Collections with a /score sub-resource (§8) and a `scored` manifest count.
 SCORED = {"smartphones", "cpus", "gpus", "socs"}

app/main.py

@@ -25,6 +25,7 @@
     monitors,
     smartphones,
     socs,
+    software,
 )
 
 PREFIX = settings.api_version_prefix
@@ -88,6 +89,7 @@ async def add_request_id(
 app.include_router(laptops.router, prefix=PREFIX)
 app.include_router(monitors.router, prefix=PREFIX)
 app.include_router(games.router, prefix=PREFIX)
+app.include_router(software.router, prefix=PREFIX)
 
 
 @app.get("/", include_in_schema=False)

app/models/__init__.py

@@ -12,6 +12,7 @@
 from app.models.monitor import Monitor
 from app.models.smartphone import Smartphone
 from app.models.soc import SoC
+from app.models.software import Software
 
 __all__ = [
     "Brand",
@@ -25,4 +26,5 @@
     "Laptop",
     "Monitor",
     "Game",
+    "Software",
 ]

app/models/software.py

@@ -0,0 +1,41 @@
+"""Software model (§6.11).
+
+A software application/program. Like games, software references no Brand — its
+makers are free-text ``developers`` / ``publishers`` lists. Unscored.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime
+
+from sqlalchemy import JSON, Column
+from sqlmodel import Field, SQLModel
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class Software(SQLModel, table=True):
+    """A software product (e.g. Blender, Firefox)."""
+
+    __tablename__ = "software"
+
+    id: int | None = Field(default=None, primary_key=True)
+    slug: str = Field(index=True, unique=True)
+    name: str
+
+    release_date: date | None = None
+
+    developers: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    publishers: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    operating_systems: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    programming_languages: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    licenses: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    genres: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+
+    # Meta
+    verified: bool = False
+    source_urls: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)

app/routers/software.py

@@ -0,0 +1,62 @@
+"""Software endpoints (§6.11). List + detail; software is unscored."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Query
+from sqlalchemy import func
+from sqlmodel import select
+from sqlmodel.sql.expression import SelectOfScalar
+
+from app.dependencies import PaginationDep, SessionDep
+from app.errors import APIError, not_found
+from app.models.software import Software
+from app.routers.utils import build_ref_page
+from app.schemas.common import Page, ResourceRef
+from app.schemas.serializers import resource_ref, software_read
+from app.schemas.software import SoftwareRead
+
+router = APIRouter(prefix="/software", tags=["software"])
+
+_SORT_FIELDS: dict[str, Any] = {
+    "name": Software.name,
+    "release_date": Software.release_date,
+}
+
+
+def _apply_sort(stmt: SelectOfScalar[Any], sort: str | None) -> SelectOfScalar[Any]:
+    if not sort:
+        return stmt.order_by(Software.name)
+    descending = sort.startswith("-")
+    field = sort[1:] if descending else sort
+    column = _SORT_FIELDS.get(field)
+    if column is None:
+        raise APIError(400, "INVALID_REQUEST", f"Cannot sort by '{field}'")
+    return stmt.order_by(column.desc() if descending else column.asc())
+
+
+@router.get("", summary="List software")
+def list_software(
+    session: SessionDep,
+    pagination: PaginationDep,
+    sort: Annotated[str | None, Query()] = None,
+) -> Page[ResourceRef]:
+    count = session.exec(select(func.count()).select_from(Software)).one()
+    list_stmt = _apply_sort(select(Software), sort)
+    list_stmt = list_stmt.offset(pagination.offset).limit(pagination.limit)
+    rows = session.exec(list_stmt).all()
+
+    refs = [resource_ref("software", row.slug, row.name) for row in rows]
+    applied = {k: v for k, v in (("sort", sort),) if v}
+    return build_ref_page(
+        refs, count=count, path="/v1/software", pagination=pagination, filters=applied
+    )
+
+
+@router.get("/{slug}", summary="Get a software product")
+def get_software(slug: str, session: SessionDep) -> SoftwareRead:
+    software = session.exec(select(Software).where(Software.slug == slug)).first()
+    if software is None:
+        raise not_found("Software", slug)
+    return software_read(software)

app/schemas/__init__.py

@@ -7,6 +7,7 @@
 from app.schemas.monitor import MonitorRead
 from app.schemas.smartphone import ScoreRead, SmartphoneRead
 from app.schemas.soc import SoCManufacturer, SoCRead, SoCSummary
+from app.schemas.software import SoftwareRead
 
 __all__ = [
     "Page",
@@ -23,4 +24,5 @@
     "LaptopRead",
     "MonitorRead",
     "GameRead",
+    "SoftwareRead",
 ]

app/schemas/serializers.py

@@ -12,6 +12,7 @@
 from app.models.monitor import Monitor
 from app.models.smartphone import Smartphone
 from app.models.soc import SoC
+from app.models.software import Software
 from app.schemas.brand import BrandRead, BrandSummary
 from app.schemas.common import HybridRead, ManufacturerRef, ResourceRef
 from app.schemas.cpu import CPURead, CPUScoreRead
@@ -22,6 +23,7 @@
 from app.schemas.monitor import MonitorRead
 from app.schemas.smartphone import ScoreRead, SmartphoneRead
 from app.schemas.soc import SoCManufacturer, SoCRead, SoCScoreRead, SoCSummary
+from app.schemas.software import SoftwareRead
 from app.services.scoring import CPUScore, GPUScore, Hybrid, PhoneScore, SoCScore
 
 PREFIX = settings.api_version_prefix
@@ -405,3 +407,24 @@ def game_read(game: Game) -> GameRead:
         updated_at=game.updated_at,
         url=url_for("games", game.slug),
     )
+
+
+def software_read(software: Software) -> SoftwareRead:
+    assert software.id is not None
+    return SoftwareRead(
+        id=software.id,
+        slug=software.slug,
+        name=software.name,
+        release_date=software.release_date,
+        developers=software.developers,
+        publishers=software.publishers,
+        operating_systems=software.operating_systems,
+        programming_languages=software.programming_languages,
+        licenses=software.licenses,
+        genres=software.genres,
+        verified=software.verified,
+        source_urls=software.source_urls,
+        created_at=software.created_at,
+        updated_at=software.updated_at,
+        url=url_for("software", software.slug),
+    )

app/schemas/software.py

@@ -0,0 +1,27 @@
+"""Software response schema (§6.11). Software is unscored (no ``score`` field)."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from pydantic import BaseModel
+
+
+class SoftwareRead(BaseModel):
+    """Full software detail response."""
+
+    id: int
+    slug: str
+    name: str
+    release_date: date | None = None
+    developers: list[str]
+    publishers: list[str]
+    operating_systems: list[str]
+    programming_languages: list[str]
+    licenses: list[str]
+    genres: list[str]
+    verified: bool
+    source_urls: list[str]
+    created_at: datetime
+    updated_at: datetime
+    url: str

app/seed.py

@@ -33,6 +33,7 @@
 from app.models.monitor import Monitor
 from app.models.smartphone import Smartphone
 from app.models.soc import SoC
+from app.models.software import Software
 
 DATA_DIR = get_data_root()
 
@@ -69,6 +70,7 @@ def seed(session: Session, data_dir: Path = DATA_DIR) -> dict[str, int]:
         "laptops": 0,
         "monitors": 0,
         "games": 0,
+        "software": 0,
     }
 
     # --- Brands ---
@@ -233,6 +235,15 @@ def seed_mobile_devices(subdir: str, model: type[SQLModel], count_key: str) -> N
         counts["games"] += 1
     session.commit()
 
+    # --- Software (standalone; no brand FK) ---
+    software_slugs = _existing_slugs(session, Software)
+    for record in _load_dir(data_dir / "software"):
+        if record["slug"] in software_slugs:
+            continue
+        session.add(Software(**record))
+        counts["software"] += 1
+    session.commit()
+
     return counts