scigantic-cards 0.1.0__tar.gz

scigantic_cards-0.1.0/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+Copyright 2026 Scigantic
+
+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.
+
+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.

scigantic_cards-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: scigantic-cards
+Version: 0.1.0
+Summary: A small data card format and linter for LLM agents: record what differs from the well-known dataset, how big it is, and how to open it.
+Author: Scigantic
+License: MIT-0
+Keywords: llm,agents,datasets,data-card,schema,lint
+Classifier: License :: OSI Approved :: MIT No Attribution License (MIT-0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Dynamic: license-file
+
+# scigantic-cards
+
+A JSON format for describing a dataset to an LLM agent, and a linter for it.
+
+A card holds what the agent is unlikely to know already: which published dataset this is, how this copy differs from it, how large it is, and a snippet that opens it. A card that only restates what the model already knows fails the lint.
+
+## Install
+
+```
+pip install scigantic-cards
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Format
+
+A card is a JSON object. Only `name` is required for the file to load. The linter checks the rest.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | string | Short id for the card |
+| `identity` | string | The published dataset, release or paper this copy comes from |
+| `summary` | string | One or two sentences |
+| `layout` | string | How files are organized |
+| `approx_bytes`, `approx_items` | integer or null | Size, for choosing between streaming and loading |
+| `fields` | list of `{name, dtype, note}` | Columns or variables |
+| `differs_from_upstream` | list of strings | How this copy differs from the well-known version |
+| `gotchas` | list of strings | Sentinel values, unit conventions, known bad files |
+| `access` | list of `{goal, snippet, verified}` | Code that opens the data. `verified` is true if you ran it |
+| `checked_at` | string | ISO date the card was last checked against the data |
+
+Unknown keys are rejected. See [`examples/acme-stations.json`](examples/acme-stations.json), a fictional dataset.
+
+The same rules are published as JSON Schema in `src/scigantic_cards/card.schema.json`, for validating cards from other languages.
+
+## Lint
+
+```
+$ scigantic-cards lint examples/needs-work.json
+examples/needs-work.json: error: identity: No identity. Name the canonical dataset, release, or paper so the agent can recall what it already knows.
+examples/needs-work.json: error: delta: No differences or gotchas. A card with neither only restates what the agent already knows.
+examples/needs-work.json: warn: size: No size. Agents choose between streaming and loading based on it.
+examples/needs-work.json: warn: unverified-access: 'List files': snippet was not executed.
+examples/needs-work.json: error: tilde-path: 'List files': a path starting with ~/ is not expanded by Python unless it goes through os.path.expanduser or Path.expanduser.
+examples/needs-work.json: warn: checked-at: checked_at is missing or not an ISO date (YYYY-MM-DD).
+```
+
+Options: `--strict` counts warnings as failures. `--budget N` sets the size limit in bytes (default 4000).
+
+Exit codes: 0 no problems, 1 lint errors (or warnings with `--strict`), 2 a file could not be read or is not a valid card.
+
+### Rules
+
+| Rule | Severity | Fires when |
+|---|---|---|
+| `name` | error | name is blank |
+| `identity` | error | identity is blank |
+| `delta` | error | `differs_from_upstream` and `gotchas` have no non-blank entry |
+| `access` | error | there are no access snippets |
+| `empty-snippet` | error | a snippet is blank |
+| `tilde-path` | error | a snippet has a string starting with `~/` and no `expanduser` |
+| `size` | warn | neither size field is set |
+| `unverified-access` | warn | a snippet has `verified: false` |
+| `field-dtype` | warn | a field has no dtype |
+| `field-duplicate` | warn | a field name appears twice |
+| `checked-at` | warn | `checked_at` is not an ISO date |
+| `budget` | warn | the card is over the budget as compact UTF-8 JSON |
+
+## Python
+
+```python
+from scigantic_cards import Card, CardError, lint
+
+try:
+    card = Card.from_json(open("card.json", encoding="utf-8").read())
+except CardError as e:
+    print(e)  # for example: card.fields[2].dtype: required
+else:
+    for issue in lint(card):
+        print(issue.severity, issue.rule, issue.message)
+```
+
+`Card.from_dict` and `Card.from_json` accept the same documents as the JSON Schema and raise `CardError` with the path of the bad value otherwise.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The suite includes property-based tests (Hypothesis) that generate valid and slightly broken cards and check that the Python loader and the JSON Schema agree on every one.
+
+## License
+
+MIT-0.

scigantic_cards-0.1.0/README.md

@@ -0,0 +1,96 @@
+# scigantic-cards
+
+A JSON format for describing a dataset to an LLM agent, and a linter for it.
+
+A card holds what the agent is unlikely to know already: which published dataset this is, how this copy differs from it, how large it is, and a snippet that opens it. A card that only restates what the model already knows fails the lint.
+
+## Install
+
+```
+pip install scigantic-cards
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Format
+
+A card is a JSON object. Only `name` is required for the file to load. The linter checks the rest.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | string | Short id for the card |
+| `identity` | string | The published dataset, release or paper this copy comes from |
+| `summary` | string | One or two sentences |
+| `layout` | string | How files are organized |
+| `approx_bytes`, `approx_items` | integer or null | Size, for choosing between streaming and loading |
+| `fields` | list of `{name, dtype, note}` | Columns or variables |
+| `differs_from_upstream` | list of strings | How this copy differs from the well-known version |
+| `gotchas` | list of strings | Sentinel values, unit conventions, known bad files |
+| `access` | list of `{goal, snippet, verified}` | Code that opens the data. `verified` is true if you ran it |
+| `checked_at` | string | ISO date the card was last checked against the data |
+
+Unknown keys are rejected. See [`examples/acme-stations.json`](examples/acme-stations.json), a fictional dataset.
+
+The same rules are published as JSON Schema in `src/scigantic_cards/card.schema.json`, for validating cards from other languages.
+
+## Lint
+
+```
+$ scigantic-cards lint examples/needs-work.json
+examples/needs-work.json: error: identity: No identity. Name the canonical dataset, release, or paper so the agent can recall what it already knows.
+examples/needs-work.json: error: delta: No differences or gotchas. A card with neither only restates what the agent already knows.
+examples/needs-work.json: warn: size: No size. Agents choose between streaming and loading based on it.
+examples/needs-work.json: warn: unverified-access: 'List files': snippet was not executed.
+examples/needs-work.json: error: tilde-path: 'List files': a path starting with ~/ is not expanded by Python unless it goes through os.path.expanduser or Path.expanduser.
+examples/needs-work.json: warn: checked-at: checked_at is missing or not an ISO date (YYYY-MM-DD).
+```
+
+Options: `--strict` counts warnings as failures. `--budget N` sets the size limit in bytes (default 4000).
+
+Exit codes: 0 no problems, 1 lint errors (or warnings with `--strict`), 2 a file could not be read or is not a valid card.
+
+### Rules
+
+| Rule | Severity | Fires when |
+|---|---|---|
+| `name` | error | name is blank |
+| `identity` | error | identity is blank |
+| `delta` | error | `differs_from_upstream` and `gotchas` have no non-blank entry |
+| `access` | error | there are no access snippets |
+| `empty-snippet` | error | a snippet is blank |
+| `tilde-path` | error | a snippet has a string starting with `~/` and no `expanduser` |
+| `size` | warn | neither size field is set |
+| `unverified-access` | warn | a snippet has `verified: false` |
+| `field-dtype` | warn | a field has no dtype |
+| `field-duplicate` | warn | a field name appears twice |
+| `checked-at` | warn | `checked_at` is not an ISO date |
+| `budget` | warn | the card is over the budget as compact UTF-8 JSON |
+
+## Python
+
+```python
+from scigantic_cards import Card, CardError, lint
+
+try:
+    card = Card.from_json(open("card.json", encoding="utf-8").read())
+except CardError as e:
+    print(e)  # for example: card.fields[2].dtype: required
+else:
+    for issue in lint(card):
+        print(issue.severity, issue.rule, issue.message)
+```
+
+`Card.from_dict` and `Card.from_json` accept the same documents as the JSON Schema and raise `CardError` with the path of the bad value otherwise.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The suite includes property-based tests (Hypothesis) that generate valid and slightly broken cards and check that the Python loader and the JSON Schema agree on every one.
+
+## License
+
+MIT-0.

scigantic_cards-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scigantic-cards"
+version = "0.1.0"
+description = "A small data card format and linter for LLM agents: record what differs from the well-known dataset, how big it is, and how to open it."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT-0" }
+authors = [{ name = "Scigantic" }]
+keywords = ["llm", "agents", "datasets", "data-card", "schema", "lint"]
+classifiers = [
+  "License :: OSI Approved :: MIT No Attribution License (MIT-0)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "mypy", "jsonschema", "hypothesis"]
+
+[project.scripts]
+scigantic-cards = "scigantic_cards.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scigantic_cards = ["py.typed", "card.schema.json"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

scigantic_cards-0.1.0/setup.cfg

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

scigantic_cards-0.1.0/src/scigantic_cards/__init__.py

@@ -0,0 +1,4 @@
+from .card import Access, Card, CardError, Field
+from .lint import Issue, lint
+
+__all__ = ["Access", "Card", "CardError", "Field", "Issue", "lint"]

scigantic_cards-0.1.0/src/scigantic_cards/card.py

@@ -0,0 +1,185 @@
+"""Card data model and strict loading.
+
+`Card.from_dict` accepts exactly the documents that `card.schema.json`
+accepts, and raises `CardError` with a path to the offending value
+otherwise.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+class CardError(ValueError):
+    """The input is not a valid card."""
+
+
+@dataclass
+class Field:
+    name: str
+    dtype: str
+    note: str = ""
+
+
+@dataclass
+class Access:
+    """A way to open the data. `verified` means the snippet was executed."""
+
+    goal: str
+    snippet: str
+    verified: bool = False
+
+
+@dataclass
+class Card:
+    name: str
+    identity: str = ""
+    summary: str = ""
+    layout: str = ""
+    approx_bytes: int | None = None
+    approx_items: int | None = None
+    fields: list[Field] = field(default_factory=list)
+    differs_from_upstream: list[str] = field(default_factory=list)
+    gotchas: list[str] = field(default_factory=list)
+    access: list[Access] = field(default_factory=list)
+    checked_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def compact_size(self) -> int:
+        """UTF-8 bytes of the compact JSON form. This is what the budget measures."""
+        text = json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"))
+        return len(text.encode("utf-8"))
+
+    @classmethod
+    def from_dict(cls, d: Any) -> "Card":
+        obj = _obj(d, "card")
+        _no_extra(obj, _TOP_KEYS, "card")
+        if "name" not in obj:
+            raise CardError("card.name: required")
+        name = _str(obj["name"], "card.name")
+        if not name:
+            raise CardError("card.name: must not be empty")
+        return cls(
+            name=name,
+            identity=_str(obj.get("identity", ""), "card.identity"),
+            summary=_str(obj.get("summary", ""), "card.summary"),
+            layout=_str(obj.get("layout", ""), "card.layout"),
+            approx_bytes=_count(obj.get("approx_bytes"), "card.approx_bytes"),
+            approx_items=_count(obj.get("approx_items"), "card.approx_items"),
+            fields=[
+                _field(x, f"card.fields[{i}]")
+                for i, x in enumerate(_list(obj.get("fields", []), "card.fields"))
+            ],
+            differs_from_upstream=_strs(
+                obj.get("differs_from_upstream", []), "card.differs_from_upstream"
+            ),
+            gotchas=_strs(obj.get("gotchas", []), "card.gotchas"),
+            access=[
+                _access(x, f"card.access[{i}]")
+                for i, x in enumerate(_list(obj.get("access", []), "card.access"))
+            ],
+            checked_at=_str(obj.get("checked_at", ""), "card.checked_at"),
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> "Card":
+        try:
+            data = json.loads(text)
+        except RecursionError:
+            raise CardError("JSON is nested too deeply") from None
+        except json.JSONDecodeError as e:
+            raise CardError(f"invalid JSON: {e}") from None
+        return cls.from_dict(data)
+
+
+_TOP_KEYS = {
+    "name", "identity", "summary", "layout", "approx_bytes", "approx_items",
+    "fields", "differs_from_upstream", "gotchas", "access", "checked_at",
+}
+
+
+def _obj(v: Any, where: str) -> dict[str, Any]:
+    if not isinstance(v, dict):
+        raise CardError(f"{where}: expected an object, got {_kind(v)}")
+    return v
+
+
+def _list(v: Any, where: str) -> list[Any]:
+    if not isinstance(v, list):
+        raise CardError(f"{where}: expected an array, got {_kind(v)}")
+    return v
+
+
+def _str(v: Any, where: str) -> str:
+    if not isinstance(v, str):
+        raise CardError(f"{where}: expected a string, got {_kind(v)}")
+    return v
+
+
+def _strs(v: Any, where: str) -> list[str]:
+    return [_str(x, f"{where}[{i}]") for i, x in enumerate(_list(v, where))]
+
+
+def _count(v: Any, where: str) -> int | None:
+    if v is None:
+        return None
+    if isinstance(v, bool):
+        raise CardError(f"{where}: expected an integer, got boolean")
+    if isinstance(v, float) and v.is_integer():
+        v = int(v)
+    if not isinstance(v, int):
+        raise CardError(f"{where}: expected an integer, got {_kind(v)}")
+    if v < 0:
+        raise CardError(f"{where}: must not be negative")
+    return v
+
+
+def _no_extra(obj: dict[str, Any], allowed: set[str], where: str) -> None:
+    extra = sorted(set(obj) - allowed)
+    if extra:
+        raise CardError(f"{where}: unknown key {extra[0]!r}")
+
+
+def _field(v: Any, where: str) -> Field:
+    obj = _obj(v, where)
+    _no_extra(obj, {"name", "dtype", "note"}, where)
+    for k in ("name", "dtype"):
+        if k not in obj:
+            raise CardError(f"{where}.{k}: required")
+    return Field(
+        name=_str(obj["name"], f"{where}.name"),
+        dtype=_str(obj["dtype"], f"{where}.dtype"),
+        note=_str(obj.get("note", ""), f"{where}.note"),
+    )
+
+
+def _access(v: Any, where: str) -> Access:
+    obj = _obj(v, where)
+    _no_extra(obj, {"goal", "snippet", "verified"}, where)
+    for k in ("goal", "snippet"):
+        if k not in obj:
+            raise CardError(f"{where}.{k}: required")
+    verified = obj.get("verified", False)
+    if not isinstance(verified, bool):
+        raise CardError(f"{where}.verified: expected a boolean, got {_kind(verified)}")
+    return Access(
+        goal=_str(obj["goal"], f"{where}.goal"),
+        snippet=_str(obj["snippet"], f"{where}.snippet"),
+        verified=verified,
+    )
+
+
+def _kind(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "boolean"
+    if isinstance(v, (int, float)):
+        return "number"
+    return type(v).__name__

scigantic_cards-0.1.0/src/scigantic_cards/card.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "scigantic-cards card",
+  "type": "object",
+  "required": ["name"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {"type": "string", "minLength": 1},
+    "identity": {"type": "string"},
+    "summary": {"type": "string"},
+    "layout": {"type": "string"},
+    "approx_bytes": {"type": ["integer", "null"], "minimum": 0},
+    "approx_items": {"type": ["integer", "null"], "minimum": 0},
+    "fields": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "dtype"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string"},
+          "dtype": {"type": "string"},
+          "note": {"type": "string"}
+        }
+      }
+    },
+    "differs_from_upstream": {"type": "array", "items": {"type": "string"}},
+    "gotchas": {"type": "array", "items": {"type": "string"}},
+    "access": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["goal", "snippet"],
+        "additionalProperties": false,
+        "properties": {
+          "goal": {"type": "string"},
+          "snippet": {"type": "string"},
+          "verified": {"type": "boolean"}
+        }
+      }
+    },
+    "checked_at": {"type": "string"}
+  }
+}

scigantic_cards-0.1.0/src/scigantic_cards/cli.py

@@ -0,0 +1,50 @@
+"""Command line entry point: scigantic-cards lint card.json [--budget N] [--strict].
+
+Exit codes: 0 no problems, 1 lint errors (or warnings with --strict),
+2 a file could not be read or is not a valid card.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .card import Card, CardError
+from .lint import DEFAULT_BYTE_BUDGET, lint
+
+MAX_BYTES = 5_000_000
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="scigantic-cards")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    lp = sub.add_parser("lint", help="lint one or more card files")
+    lp.add_argument("files", nargs="+")
+    lp.add_argument("--budget", type=int, default=DEFAULT_BYTE_BUDGET)
+    lp.add_argument("--strict", action="store_true", help="treat warnings as errors")
+    args = p.parse_args(argv)
+
+    code = 0
+    for path in args.files:
+        try:
+            card = _load(path)
+        except (OSError, CardError, UnicodeDecodeError) as e:
+            print(f"{path}: cannot load: {e}", file=sys.stderr)
+            code = 2
+            continue
+        for issue in lint(card, byte_budget=args.budget):
+            print(f"{path}: {issue.severity}: {issue.rule}: {issue.message}")
+            if code == 0 and (issue.severity == "error" or args.strict):
+                code = 1
+    return code
+
+
+def _load(path: str) -> Card:
+    with open(path, "rb") as fh:
+        raw = fh.read(MAX_BYTES + 1)
+    if len(raw) > MAX_BYTES:
+        raise CardError(f"file is larger than {MAX_BYTES} bytes")
+    return Card.from_json(raw.decode("utf-8-sig"))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scigantic_cards-0.1.0/src/scigantic_cards/lint.py

@@ -0,0 +1,98 @@
+"""Lint a card. Each rule yields zero or more Issue objects."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date
+
+from .card import Card
+
+DEFAULT_BYTE_BUDGET = 4000
+
+# A string literal that starts with ~/ . Python does not expand it in glob(),
+# open(), Path() or os.listdir().
+_TILDE_PATH = re.compile(r"""['"]~/""")
+
+
+@dataclass
+class Issue:
+    rule: str
+    severity: str  # "error" or "warn"
+    message: str
+
+
+def lint(card: Card, byte_budget: int = DEFAULT_BYTE_BUDGET) -> list[Issue]:
+    out: list[Issue] = []
+
+    if not card.name.strip():
+        out.append(Issue("name", "error", "Name is blank."))
+
+    if not card.identity.strip():
+        out.append(Issue(
+            "identity", "error",
+            "No identity. Name the canonical dataset, release, or paper so the "
+            "agent can recall what it already knows.",
+        ))
+
+    differences = [s for s in card.differs_from_upstream + card.gotchas if s.strip()]
+    if not differences:
+        out.append(Issue(
+            "delta", "error",
+            "No differences or gotchas. A card with neither only restates what "
+            "the agent already knows.",
+        ))
+
+    if card.approx_bytes is None and card.approx_items is None:
+        out.append(Issue(
+            "size", "warn",
+            "No size. Agents choose between streaming and loading based on it.",
+        ))
+
+    if not card.access:
+        out.append(Issue("access", "error", "No access snippet."))
+    for a in card.access:
+        goal = a.goal.strip() or "(no goal)"
+        if not a.snippet.strip():
+            out.append(Issue("empty-snippet", "error", f"'{goal}': snippet is empty."))
+        if not a.verified:
+            out.append(Issue(
+                "unverified-access", "warn", f"'{goal}': snippet was not executed.",
+            ))
+        if _TILDE_PATH.search(a.snippet) and "expanduser" not in a.snippet:
+            out.append(Issue(
+                "tilde-path", "error",
+                f"'{goal}': a path starting with ~/ is not expanded by Python "
+                "unless it goes through os.path.expanduser or Path.expanduser.",
+            ))
+
+    seen: set[str] = set()
+    for f in card.fields:
+        if not f.dtype.strip():
+            out.append(Issue("field-dtype", "warn", f"Field '{f.name}' has no dtype."))
+        if f.name in seen:
+            out.append(Issue("field-duplicate", "warn", f"Field '{f.name}' is listed twice."))
+        seen.add(f.name)
+
+    if not _is_iso_date(card.checked_at):
+        out.append(Issue(
+            "checked-at", "warn", "checked_at is missing or not an ISO date (YYYY-MM-DD).",
+        ))
+
+    size = card.compact_size()
+    if size > byte_budget:
+        out.append(Issue(
+            "budget", "warn",
+            f"Card is {size} bytes as compact JSON, over the {byte_budget} byte "
+            "budget. Cut what the agent would already know.",
+        ))
+    return out
+
+
+def _is_iso_date(s: str) -> bool:
+    if len(s) < 10 or (len(s) > 10 and s[10] not in "T "):
+        return False
+    try:
+        date.fromisoformat(s[:10])
+    except ValueError:
+        return False
+    return True

scigantic_cards-0.1.0/src/scigantic_cards.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: scigantic-cards
+Version: 0.1.0
+Summary: A small data card format and linter for LLM agents: record what differs from the well-known dataset, how big it is, and how to open it.
+Author: Scigantic
+License: MIT-0
+Keywords: llm,agents,datasets,data-card,schema,lint
+Classifier: License :: OSI Approved :: MIT No Attribution License (MIT-0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Dynamic: license-file
+
+# scigantic-cards
+
+A JSON format for describing a dataset to an LLM agent, and a linter for it.
+
+A card holds what the agent is unlikely to know already: which published dataset this is, how this copy differs from it, how large it is, and a snippet that opens it. A card that only restates what the model already knows fails the lint.
+
+## Install
+
+```
+pip install scigantic-cards
+```
+
+Python 3.10 or newer. No dependencies.
+
+## Format
+
+A card is a JSON object. Only `name` is required for the file to load. The linter checks the rest.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | string | Short id for the card |
+| `identity` | string | The published dataset, release or paper this copy comes from |
+| `summary` | string | One or two sentences |
+| `layout` | string | How files are organized |
+| `approx_bytes`, `approx_items` | integer or null | Size, for choosing between streaming and loading |
+| `fields` | list of `{name, dtype, note}` | Columns or variables |
+| `differs_from_upstream` | list of strings | How this copy differs from the well-known version |
+| `gotchas` | list of strings | Sentinel values, unit conventions, known bad files |
+| `access` | list of `{goal, snippet, verified}` | Code that opens the data. `verified` is true if you ran it |
+| `checked_at` | string | ISO date the card was last checked against the data |
+
+Unknown keys are rejected. See [`examples/acme-stations.json`](examples/acme-stations.json), a fictional dataset.
+
+The same rules are published as JSON Schema in `src/scigantic_cards/card.schema.json`, for validating cards from other languages.
+
+## Lint
+
+```
+$ scigantic-cards lint examples/needs-work.json
+examples/needs-work.json: error: identity: No identity. Name the canonical dataset, release, or paper so the agent can recall what it already knows.
+examples/needs-work.json: error: delta: No differences or gotchas. A card with neither only restates what the agent already knows.
+examples/needs-work.json: warn: size: No size. Agents choose between streaming and loading based on it.
+examples/needs-work.json: warn: unverified-access: 'List files': snippet was not executed.
+examples/needs-work.json: error: tilde-path: 'List files': a path starting with ~/ is not expanded by Python unless it goes through os.path.expanduser or Path.expanduser.
+examples/needs-work.json: warn: checked-at: checked_at is missing or not an ISO date (YYYY-MM-DD).
+```
+
+Options: `--strict` counts warnings as failures. `--budget N` sets the size limit in bytes (default 4000).
+
+Exit codes: 0 no problems, 1 lint errors (or warnings with `--strict`), 2 a file could not be read or is not a valid card.
+
+### Rules
+
+| Rule | Severity | Fires when |
+|---|---|---|
+| `name` | error | name is blank |
+| `identity` | error | identity is blank |
+| `delta` | error | `differs_from_upstream` and `gotchas` have no non-blank entry |
+| `access` | error | there are no access snippets |
+| `empty-snippet` | error | a snippet is blank |
+| `tilde-path` | error | a snippet has a string starting with `~/` and no `expanduser` |
+| `size` | warn | neither size field is set |
+| `unverified-access` | warn | a snippet has `verified: false` |
+| `field-dtype` | warn | a field has no dtype |
+| `field-duplicate` | warn | a field name appears twice |
+| `checked-at` | warn | `checked_at` is not an ISO date |
+| `budget` | warn | the card is over the budget as compact UTF-8 JSON |
+
+## Python
+
+```python
+from scigantic_cards import Card, CardError, lint
+
+try:
+    card = Card.from_json(open("card.json", encoding="utf-8").read())
+except CardError as e:
+    print(e)  # for example: card.fields[2].dtype: required
+else:
+    for issue in lint(card):
+        print(issue.severity, issue.rule, issue.message)
+```
+
+`Card.from_dict` and `Card.from_json` accept the same documents as the JSON Schema and raise `CardError` with the path of the bad value otherwise.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The suite includes property-based tests (Hypothesis) that generate valid and slightly broken cards and check that the Python loader and the JSON Schema agree on every one.
+
+## License
+
+MIT-0.

scigantic_cards-0.1.0/src/scigantic_cards.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/scigantic_cards/__init__.py
+src/scigantic_cards/card.py
+src/scigantic_cards/card.schema.json
+src/scigantic_cards/cli.py
+src/scigantic_cards/lint.py
+src/scigantic_cards/py.typed
+src/scigantic_cards.egg-info/PKG-INFO
+src/scigantic_cards.egg-info/SOURCES.txt
+src/scigantic_cards.egg-info/dependency_links.txt
+src/scigantic_cards.egg-info/entry_points.txt
+src/scigantic_cards.egg-info/requires.txt
+src/scigantic_cards.egg-info/top_level.txt
+tests/test_lint.py
+tests/test_load.py
+tests/test_stress.py

scigantic_cards-0.1.0/src/scigantic_cards.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

scigantic_cards-0.1.0/src/scigantic_cards.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scigantic-cards = scigantic_cards.cli:main

scigantic_cards-0.1.0/src/scigantic_cards.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest
+mypy
+jsonschema
+hypothesis

scigantic_cards-0.1.0/src/scigantic_cards.egg-info/top_level.txt

@@ -0,0 +1 @@
+scigantic_cards

scigantic_cards-0.1.0/tests/test_lint.py

@@ -0,0 +1,96 @@
+"""One positive and one negative case per rule."""
+import pytest
+
+from scigantic_cards import Access, Field, lint
+from conftest import make_card
+
+
+def rules(card, **kw):
+    return {i.rule for i in lint(card, **kw)}
+
+
+def test_clean_card_has_no_issues():
+    assert lint(make_card()) == []
+
+
+@pytest.mark.parametrize("overrides,rule", [
+    ({"name": "  "}, "name"),
+    ({"identity": ""}, "identity"),
+    ({"identity": "   \n"}, "identity"),
+    ({"differs_from_upstream": []}, "delta"),
+    ({"differs_from_upstream": ["", "  "]}, "delta"),
+    ({"approx_bytes": None}, "size"),
+    ({"access": []}, "access"),
+    ({"access": [Access("g", "   ", True)]}, "empty-snippet"),
+    ({"access": [Access("g", "x = 1", False)]}, "unverified-access"),
+    ({"fields": [Field("a", "")]}, "field-dtype"),
+    ({"fields": [Field("a", "int"), Field("a", "str")]}, "field-duplicate"),
+    ({"checked_at": ""}, "checked-at"),
+    ({"checked_at": "yesterday"}, "checked-at"),
+    ({"checked_at": "2026-13-40"}, "checked-at"),
+    ({"checked_at": "2026-10-11x"}, "checked-at"),
+    ({"gotchas": ["x" * 5000]}, "budget"),
+])
+def test_rule_fires(overrides, rule):
+    assert rule in rules(make_card(**overrides))
+
+
+@pytest.mark.parametrize("snippet", [
+    "glob.glob('~/data/*.nc')",
+    'open("~/x.csv")',
+    "Path('~/data').iterdir()",
+    "os.listdir('~/d')",
+])
+def test_tilde_path_fires(snippet):
+    assert "tilde-path" in rules(make_card(access=[Access("g", snippet, True)]))
+
+
+@pytest.mark.parametrize("snippet", [
+    "glob.glob(os.path.expanduser('~/data/*.nc'))",
+    "Path('~/data').expanduser()",
+    "url = 'https://example.org/~user/x'",
+    "s3://bucket/~/x",
+])
+def test_tilde_path_quiet(snippet):
+    assert "tilde-path" not in rules(make_card(access=[Access("g", snippet, True)]))
+
+
+@pytest.mark.parametrize("value", ["2026-10-11", "2026-10-11T08:00:00Z", "2026-10-11 08:00"])
+def test_checked_at_accepts(value):
+    assert "checked-at" not in rules(make_card(checked_at=value))
+
+
+def test_either_differs_or_gotchas_satisfies_delta():
+    assert "delta" not in rules(make_card(differs_from_upstream=[], gotchas=["x"]))
+
+
+def test_one_size_field_is_enough():
+    assert "size" not in rules(make_card(approx_bytes=None, approx_items=5))
+
+
+def test_zero_size_counts_as_given():
+    assert "size" not in rules(make_card(approx_bytes=0))
+
+
+def test_budget_is_configurable():
+    c = make_card()
+    assert "budget" in rules(c, byte_budget=10)
+    assert "budget" not in rules(c, byte_budget=10_000)
+
+
+def test_budget_counts_utf8_bytes_not_escapes():
+    # 1000 CJK characters are 3000 UTF-8 bytes. With ensure_ascii escaping the
+    # same text would be counted as 6000 bytes and trip a 4000 budget.
+    c = make_card(gotchas=["字" * 1000])
+    assert 3000 < c.compact_size() < 3400
+    assert "budget" not in rules(c)
+
+
+def test_one_issue_per_unverified_snippet():
+    c = make_card(access=[Access("a", "x", False), Access("b", "y", False)])
+    assert [i.rule for i in lint(c)].count("unverified-access") == 2
+
+
+def test_lint_is_deterministic():
+    c = make_card(identity="", access=[])
+    assert lint(c) == lint(c)

scigantic_cards-0.1.0/tests/test_load.py

@@ -0,0 +1,77 @@
+import json
+
+import pytest
+
+from scigantic_cards import Card, CardError
+from conftest import make_card
+
+
+def test_round_trip():
+    c = make_card(gotchas=["a", "b"])
+    assert Card.from_json(c.to_json()) == c
+    assert Card.from_json(c.to_json(indent=None)) == c
+
+
+def test_round_trip_non_ascii():
+    c = make_card(identity="Données d'été, 日本語, 🙂")
+    assert Card.from_json(c.to_json()) == c
+    assert "日本語" in c.to_json()
+
+
+def test_minimal_card():
+    c = Card.from_dict({"name": "x"})
+    assert c.fields == [] and c.approx_bytes is None
+
+
+@pytest.mark.parametrize("doc,where", [
+    ([], "card"),
+    ("x", "card"),
+    (None, "card"),
+    ({}, "card.name"),
+    ({"name": ""}, "card.name"),
+    ({"name": 5}, "card.name"),
+    ({"name": None}, "card.name"),
+    ({"name": "x", "extra": 1}, "extra"),
+    ({"name": "x", "approx_bytes": -1}, "card.approx_bytes"),
+    ({"name": "x", "approx_bytes": True}, "card.approx_bytes"),
+    ({"name": "x", "approx_bytes": 1.5}, "card.approx_bytes"),
+    ({"name": "x", "approx_bytes": "10"}, "card.approx_bytes"),
+    ({"name": "x", "approx_bytes": float("nan")}, "card.approx_bytes"),
+    ({"name": "x", "approx_bytes": float("inf")}, "card.approx_bytes"),
+    ({"name": "x", "fields": "a"}, "card.fields"),
+    ({"name": "x", "fields": [1]}, "card.fields[0]"),
+    ({"name": "x", "fields": [{"name": "a"}]}, "card.fields[0].dtype"),
+    ({"name": "x", "fields": [{"name": "a", "dtype": "i", "z": 1}]}, "z"),
+    ({"name": "x", "gotchas": "a"}, "card.gotchas"),
+    ({"name": "x", "gotchas": ["a", 2]}, "card.gotchas[1]"),
+    ({"name": "x", "access": [{"goal": "g"}]}, "card.access[0].snippet"),
+    ({"name": "x", "access": [{"goal": "g", "snippet": "s", "verified": "yes"}]},
+     "card.access[0].verified"),
+])
+def test_rejects_with_path(doc, where):
+    with pytest.raises(CardError) as e:
+        Card.from_dict(doc)
+    assert where in str(e.value)
+
+
+def test_integral_float_is_accepted_as_int():
+    c = Card.from_dict({"name": "x", "approx_bytes": 1e9})
+    assert c.approx_bytes == 10**9 and isinstance(c.approx_bytes, int)
+
+
+def test_huge_int_is_accepted():
+    assert Card.from_dict({"name": "x", "approx_bytes": 10**40}).approx_bytes == 10**40
+
+
+def test_invalid_json_is_a_card_error():
+    with pytest.raises(CardError):
+        Card.from_json("{not json")
+
+
+def test_deep_nesting_is_a_card_error():
+    with pytest.raises(CardError):
+        Card.from_json("[" * 100_000 + "]" * 100_000)
+
+
+def test_card_error_is_a_value_error():
+    assert issubclass(CardError, ValueError)

scigantic_cards-0.1.0/tests/test_stress.py

@@ -0,0 +1,200 @@
+"""Property-based tests. The loader and the shipped JSON Schema must agree."""
+import json
+import time
+
+import jsonschema
+from hypothesis import HealthCheck, given, settings, strategies as st
+
+from scigantic_cards import Card, CardError, lint
+from scigantic_cards.cli import main
+
+SETTINGS = settings(max_examples=1500, suppress_health_check=[HealthCheck.too_slow], deadline=None)
+
+json_leaf = st.none() | st.booleans() | st.integers() | st.floats() | st.text()
+json_any = st.recursive(
+    json_leaf,
+    lambda c: st.lists(c, max_size=4) | st.dictionaries(st.text(max_size=12), c, max_size=4),
+    max_leaves=25,
+)
+
+text = st.text(max_size=30)
+good_count = st.none() | st.integers(min_value=0, max_value=10**15) | st.sampled_from([0, 1.0, 1e20, -0.0])
+edge = st.sampled_from([-1, -3, 1.5, True, False, None, "", "x", [], {}, float("nan"), float("inf")])
+bad_or_any = edge | json_any
+
+valid_field = st.fixed_dictionaries({"name": text, "dtype": text}, optional={"note": text})
+valid_access = st.fixed_dictionaries(
+    {"goal": text, "snippet": text}, optional={"verified": st.booleans()}
+)
+valid_doc = st.fixed_dictionaries(
+    {"name": st.text(min_size=1, max_size=30)},
+    optional={
+        "identity": text, "summary": text, "layout": text,
+        "approx_bytes": good_count, "approx_items": good_count,
+        "fields": st.lists(valid_field, max_size=4),
+        "differs_from_upstream": st.lists(text, max_size=4),
+        "gotchas": st.lists(text, max_size=4),
+        "access": st.lists(valid_access, max_size=4),
+        "checked_at": text,
+    },
+)
+
+COUNT_NEAR = [-1, -3, 1.5, True, False, "1", float("nan"), float("inf"), [], {}]
+STR_NEAR = [5, None, [], {}, True, 1.5]
+NEAR = {
+    "name": ["", 5, None, [], True],
+    "approx_bytes": COUNT_NEAR, "approx_items": COUNT_NEAR,
+    "fields": ["a", None, {}, [1], [None], [{}]],
+    "access": ["a", None, {}, [1], [None], [{}]],
+    "differs_from_upstream": ["a", None, {}, [1], [None]],
+    "gotchas": ["a", None, {}, [1], [None]],
+    "bogus": ["x", 1, None],
+}
+SUB_NEAR = {
+    "field": {"name": STR_NEAR, "dtype": STR_NEAR + [None], "note": STR_NEAR, "bogus": ["x", 1]},
+    "access": {"goal": STR_NEAR, "snippet": STR_NEAR, "verified": ["yes", 1, 0, None, "true"],
+               "bogus": ["x", 1]},
+}
+
+TOP = ["name", "identity", "summary", "layout", "approx_bytes", "approx_items", "fields",
+       "differs_from_upstream", "gotchas", "access", "checked_at", "bogus"]
+
+
+def _dict_items(v):
+    return isinstance(v, list) and v and all(isinstance(x, dict) for x in v)
+
+
+@st.composite
+def cardish(draw):
+    """A valid card with up to two single-value mutations, at top level or one level down."""
+    doc = draw(valid_doc)
+    for _ in range(draw(st.integers(0, 2))):
+        where = draw(st.sampled_from(["top", "field", "access", "list_item", "drop"]))
+        value = draw(bad_or_any)
+        if where == "top":
+            key = draw(st.sampled_from(TOP))
+            near = NEAR.get(key, STR_NEAR)
+            doc[key] = draw(st.sampled_from(near)) if draw(st.booleans()) else value
+        elif where == "field" and _dict_items(doc.get("fields")):
+            i = draw(st.integers(0, len(doc["fields"]) - 1))
+            key = draw(st.sampled_from(sorted(SUB_NEAR["field"])))
+            doc["fields"][i][key] = draw(st.sampled_from(SUB_NEAR["field"][key])) if draw(st.booleans()) else value
+        elif where == "access" and _dict_items(doc.get("access")):
+            i = draw(st.integers(0, len(doc["access"]) - 1))
+            key = draw(st.sampled_from(sorted(SUB_NEAR["access"])))
+            doc["access"][i][key] = draw(st.sampled_from(SUB_NEAR["access"][key])) if draw(st.booleans()) else value
+        elif where == "drop":
+            target = draw(st.sampled_from(["top", "fields", "access"]))
+            if target == "top":
+                doc.pop(draw(st.sampled_from(TOP)), None)
+            elif _dict_items(doc.get(target)):
+                item = doc[target][0]
+                item.pop(draw(st.sampled_from(sorted(item))), None)
+        elif where == "list_item":
+            key = draw(st.sampled_from(["gotchas", "differs_from_upstream", "fields", "access"]))
+            if isinstance(doc.get(key), list):
+                doc[key].append(value)
+    return doc
+
+
+def schema_accepts(schema, doc) -> bool:
+    try:
+        jsonschema.validate(doc, schema)
+        return True
+    except jsonschema.ValidationError:
+        return False
+
+
+def loader_accepts(doc) -> bool:
+    try:
+        Card.from_dict(doc)
+        return True
+    except CardError:
+        return False
+
+
+@SETTINGS
+@given(cardish())
+def test_loader_matches_schema_on_card_shaped_input(schema, doc):
+    assert loader_accepts(doc) == schema_accepts(schema, doc), doc
+
+
+@SETTINGS
+@given(json_any)
+def test_loader_matches_schema_on_arbitrary_json(schema, doc):
+    assert loader_accepts(doc) == schema_accepts(schema, doc), doc
+
+
+@SETTINGS
+@given(cardish())
+def test_accepted_cards_lint_and_round_trip(doc):
+    try:
+        card = Card.from_dict(doc)
+    except CardError:
+        return
+    lint(card)  # must not raise
+    assert Card.from_json(card.to_json()) == card
+    assert Card.from_json(card.to_json(indent=None)) == card
+
+
+@SETTINGS
+@given(json_any)
+def test_loader_only_ever_raises_card_error(doc):
+    try:
+        Card.from_dict(doc)
+    except CardError:
+        pass
+
+
+@settings(max_examples=150, deadline=None, suppress_health_check=[HealthCheck.function_scoped_fixture])
+@given(st.binary(max_size=2000))
+def test_cli_survives_arbitrary_bytes(tmp_path_factory, data):
+    p = tmp_path_factory.mktemp("f") / "card.json"
+    p.write_bytes(data)
+    assert main(["lint", str(p)]) in (0, 1, 2)
+
+
+def test_cli_survives_non_files(tmp_path):
+    assert main(["lint", str(tmp_path)]) == 2  # a directory
+    assert main(["lint", str(tmp_path / "nope.json")]) == 2
+
+
+def test_cli_handles_bom_and_crlf(tmp_path):
+    p = tmp_path / "c.json"
+    body = json.dumps({"name": "x"}, indent=2).replace("\n", "\r\n")
+    p.write_bytes(b"\xef\xbb\xbf" + body.encode())
+    assert main(["lint", str(p)]) == 1  # loads; lint errors on the empty card
+
+
+def test_cli_rejects_oversized_file(tmp_path, capsys):
+    p = tmp_path / "big.json"
+    p.write_text('{"name": "x", "summary": "' + "a" * 6_000_000 + '"}')
+    assert main(["lint", str(p)]) == 2
+    assert "larger than" in capsys.readouterr().err
+
+
+def test_cli_exit_codes_and_strict(tmp_path, capsys):
+    from conftest import make_card
+    ok = tmp_path / "ok.json"
+    ok.write_text(make_card().to_json())
+    warn = tmp_path / "warn.json"
+    warn.write_text(make_card(checked_at="").to_json())
+    bad = tmp_path / "bad.json"
+    bad.write_text("[]")
+    assert main(["lint", str(ok)]) == 0
+    assert main(["lint", str(warn)]) == 0
+    assert main(["lint", "--strict", str(warn)]) == 1
+    assert main(["lint", str(bad)]) == 2
+    # one bad file does not stop later files from being linted
+    assert main(["lint", str(bad), str(warn), "--strict"]) == 2
+    assert "warn.json" in capsys.readouterr().out
+
+
+def test_large_card_lints_quickly():
+    from conftest import make_card
+    from scigantic_cards import Field
+    card = make_card(fields=[Field(f"f{i}", "int") for i in range(100_000)])
+    t = time.perf_counter()
+    issues = lint(card)
+    assert time.perf_counter() - t < 5
+    assert any(i.rule == "budget" for i in issues)