sysml2kit 0.0.1__tar.gz → 0.1.0__tar.gz

sysml2kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.0 — 2026-08-21
+
+First working release.
+
+- Object model: the pragmatic profile (~20 element kinds) as pydantic
+  classes, `Model` container with identity/ownership/qualified names,
+  `assign_stable_ids()` (UUIDv5), fluent builder API, `AttributeValue` with
+  unit text and provenance, pint-backed unit helpers.
+- JSON interchange: Systems Modeling API serialization reader/writer,
+  deterministic output, `OpaqueElement` passthrough for unknown `@type`s;
+  json→model→json fixpoint property-tested.
+- Textual notation writer: deterministic `.sysml` output; verified against
+  the sysmlpy parser (write → parse → structural compare).
+- Traceability queries: satisfied_by/verified_by/derived_from,
+  unsatisfied/unverified requirements, allocation table, trace matrix.
+- Validation: rules S2K001–S2K009 with severities and stable ids.
+- Diff: element-level with `--by-name` matching for regenerated ids.
+- API client: hand-written httpx client for the Systems Modeling API
+  (projects/branches/commits/elements reads, create_project, push_model).
+- Parser backends: `ParserBackend` protocol; sysmlpy adapter behind the
+  `parse` extra.
+- Interop: `extract_requirements` reading the metricKey convention, with
+  dual-form thresholds for operator-style and bound-style engines.
+- CLI: `show` (`--traceability`), `validate`, `diff`, `export`
+  (`--stable-ids`), `version`.
+- Docs site, conformance-oracle workflow scaffold, prose lint tooling.
+
+## 0.0.1 — 2026-08-21
+
+- Package skeleton published to claim the PyPI name. Importable, no usable
+  functionality yet.

{sysml2kit-0.0.1 → sysml2kit-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysml2kit
-Version: 0.0.1
+Version: 0.1.0
 Summary: API-first Python tooling for building, querying, validating, and automating SysML v2 models
 Project-URL: Homepage, https://github.com/jman4162/sysml2kit
 Project-URL: Source, https://github.com/jman4162/sysml2kit
@@ -44,8 +44,10 @@ Description-Content-Type: text/markdown
 API-first Python tooling for building, querying, validating, and automating
 SysML v2 models.
 
-> **Status: pre-alpha.** The 0.0.x releases claim the package name and publish
-> the skeleton while the core lands. Pin an exact version if you depend on it.
+> **Status: pre-alpha.** The 0.1.x line has a working core (model, writer,
+> interchange, queries, validation, diff, API client, parse backend); the API
+> may still move between minor versions. Pin an exact version if you depend
+> on it.
 
 `sysml2kit` is the requirements/architecture/traceability layer for
 engineering automation stacks: build a system model in Python, emit standard

{sysml2kit-0.0.1 → sysml2kit-0.1.0}/README.md

@@ -8,8 +8,10 @@
 API-first Python tooling for building, querying, validating, and automating
 SysML v2 models.
 
-> **Status: pre-alpha.** The 0.0.x releases claim the package name and publish
-> the skeleton while the core lands. Pin an exact version if you depend on it.
+> **Status: pre-alpha.** The 0.1.x line has a working core (model, writer,
+> interchange, queries, validation, diff, API client, parse backend); the API
+> may still move between minor versions. Pin an exact version if you depend
+> on it.
 
 `sysml2kit` is the requirements/architecture/traceability layer for
 engineering automation stacks: build a system model in Python, emit standard

sysml2kit-0.1.0/docs/api-client.md

@@ -0,0 +1,28 @@
+# API client
+
+`sysml2kit.api.SysMLApiClient` is a hand-written httpx client for the OMG
+Systems Modeling API and Services endpoints (the REST binding any conformant
+model server exposes).
+
+```python
+from sysml2kit.api import SysMLApiClient
+
+with SysMLApiClient("https://models.example.com", token="…") as client:
+    for project in client.list_projects():
+        print(project.id, project.name)
+    model = client.list_elements(project_id, commit_id)   # -> sysml2kit Model
+    client.push_model(project_id, model, message="update")
+```
+
+Covered in v0.1: `list_projects`, `get_project`, `list_branches`,
+`list_commits`, `get_commit`, `get_element`, `list_elements` (returns a
+`Model` via the interchange reader), `create_project`, and `push_model`
+(POSTs a commit whose change set inserts the model's records). Branch
+management and merges are not covered yet.
+
+Failures raise `ApiError(status, detail)`. The client sends the bearer token
+to whatever base URL you configure; use HTTPS.
+
+Server compatibility note: the pilot API-Services implementation has JSON
+quirks relative to the spec; compatibility is tested best-effort behind the
+`api` pytest marker against a local server, not in default CI.

sysml2kit-0.1.0/docs/backends.md

@@ -0,0 +1,34 @@
+# Parser backends
+
+sysml2kit does not implement the SysML v2 grammar. Reading textual notation
+goes through a `ParserBackend` (see `sysml2kit.backends.protocol`):
+
+```python
+from sysml2kit.backends import get_backend
+
+backend = get_backend("sysmlpy")
+model = backend.parse(text)
+model = backend.parse_files([path_a, path_b])
+```
+
+## The sysmlpy backend
+
+`pip install sysml2kit[parse]` installs
+[sysmlpy](https://github.com/mycr0ft/sysmlpy) (MIT, ANTLR4-based). The
+adapter maps its parse tree into the pragmatic profile; constructs the
+profile lacks come back as `OpaqueElement` with a logged warning.
+
+Fidelity: sysmlpy 0.36 does not surface typing, multiplicity, or attribute
+values on its wrapper objects, so those fields are empty after a parse.
+Names, kinds, docs, and ownership round-trip; the writer-emit → parse → 
+compare test in CI pins exactly that contract. Use JSON interchange when you
+need full fidelity.
+
+The dependency is capped (`sysmlpy>=0.36.2,<0.37`) because it has a single
+maintainer; bumps are deliberate, after reading the release notes.
+
+## Conformance oracle
+
+A scheduled workflow (`conformance.yml`) downloads the EPL-2.0 OMG pilot
+implementation at run time (never vendored) and checks it accepts every
+`.sysml` file our writer emits. See `tools/conformance/run_oracle.py`.

sysml2kit-0.1.0/docs/cli.md

@@ -0,0 +1,19 @@
+# Command line
+
+`sysml2kit` accepts `.json` interchange files everywhere; `.sysml` inputs
+need the parse extra (`pip install sysml2kit[parse]`).
+
+```bash
+sysml2kit show model.json                 # element tree + counts
+sysml2kit show model.json --traceability  # + requirement-to-part matrix
+sysml2kit validate a.json b.sysml         # exit 1 on error-severity issues
+sysml2kit diff old.json new.json          # exit 1 when models differ
+sysml2kit diff old.json new.json --by-name  # match by qualified name, not id
+sysml2kit export model.sysml --to json -o model.json
+sysml2kit export model.json --to sysml
+sysml2kit export model.json --to json --stable-ids  # UUIDv5 ids for committing
+sysml2kit version
+```
+
+Exit codes: `validate` returns 1 when any error-severity issue is found;
+`diff` returns 1 when the models differ. Both suit CI gates.

sysml2kit-0.1.0/docs/concepts.md

@@ -0,0 +1,46 @@
+# Concepts
+
+## The pragmatic profile
+
+sysml2kit implements ~20 element kinds (packages, part/port/attribute
+definitions and usages, interfaces, connections, requirements, constraints,
+analysis cases, metadata, and four traceability relationships), not the full
+~270-metaclass abstract syntax. Anything outside the profile round-trips
+through `OpaqueElement`: on JSON import an unrecognized `@type` keeps its raw
+record and ownership links, and re-exports unchanged.
+
+The repo's `SPEC.md` lists the profile, the pinned spec release
+(`SysML-v2-Release` tag `2026-05`), and every known deviation.
+
+## Identity, ownership, refs
+
+- Every element has a UUID `element_id`, matching the API JSON `@id`.
+- Cross-references are `Ref` objects (UUID wrappers) resolved through the
+  model, never direct Python references, so any element serializes alone.
+- Ownership lives in the `Model` container (owner/owned maps), not on
+  elements.
+- `Model.assign_stable_ids()` rewrites ids as UUIDv5 hashes of qualified
+  names, so generated interchange files diff cleanly under version control.
+  Run it before committing generated models.
+
+## Values with units and provenance
+
+`AttributeValue` holds a literal plus optional `unit` (text, e.g. `"dBW"`),
+`source`, and `confidence`. Units stay text in the model for round-trip
+fidelity; `sysml2kit.units` (pint) checks them during validation and offers
+conversion helpers.
+
+## Two output formats, one lossless
+
+- **JSON interchange** (`sysml2kit.interchange`) is the lossless format and
+  what the Systems Modeling API speaks.
+- **Textual notation** (`sysml2kit.text`) is deterministic and parseable, but
+  relationship kinds without a standalone textual statement (verify, derive)
+  emit as marked dependencies. Round-tripping text preserves structure;
+  round-tripping JSON preserves everything.
+
+## Spec churn policy
+
+The `@type` vocabulary lives in one module
+(`sysml2kit/interchange/typemap.py`). The spec pin moves at most quarterly,
+in a minor release, noted in the changelog.

sysml2kit-0.1.0/docs/index.md

@@ -0,0 +1,24 @@
+# sysml2kit
+
+API-first Python tooling for building, querying, validating, and automating
+SysML v2 models.
+
+```bash
+pip install sysml2kit            # build, write, query, validate, diff
+pip install "sysml2kit[parse]"   # + read .sysml files (sysmlpy backend)
+```
+
+`sysml2kit` is the requirements/architecture/traceability layer for
+engineering automation stacks: build a system model in Python, emit standard
+SysML v2 textual notation and Systems Modeling API JSON, answer traceability
+questions (which requirements are unsatisfied? unverified? allocated where?),
+validate, and diff.
+
+Reference spec release: OMG `SysML-v2-Release` tag `2026-05`. The element
+subset and known deviations are documented in
+[concepts](concepts.md) and the repo's `SPEC.md`.
+
+Start with the [quickstart](quickstart.md), then the
+[traceability](traceability.md) page — the queries there are the point of the
+package. For antenna/RF domain content, see
+[the RF library](rf-library.md).

sysml2kit-0.1.0/docs/interchange.md

@@ -0,0 +1,31 @@
+# Interchange
+
+## JSON (lossless)
+
+`sysml2kit.interchange` reads and writes the Systems Modeling API
+serialization: a flat list of records like
+
+```json
+{"@id": "…", "@type": "PartUsage", "declaredName": "battery",
+ "owningRelatedElement": {"@id": "…"}, "definition": {"@id": "…"}}
+```
+
+- `model_to_json(model)` / `write_json(model, path)` — deterministic output:
+  elements sorted by qualified name, keys sorted per record, so committed
+  files diff cleanly. Pair with `model.assign_stable_ids()` for generated
+  models.
+- `model_from_json(records_or_path)` — unknown `@type` records become
+  `OpaqueElement` and re-export byte-identically.
+
+`json -> model -> json` is a fixpoint; the property is tested with hypothesis.
+
+## Textual notation (readable, parseable)
+
+`sysml2kit.text.write_model(model)` emits deterministic `.sysml` text:
+ownership order, four-space indent, values as `= 52.0 [dBW]`, requirement
+statements as `doc` bodies, `satisfy X by Y;` / `allocate X to Y;`
+statements. Verify and derive have no standalone textual statement in the
+grammar, so they emit as `dependency from A to B; // verify` — the JSON keeps
+the precise kind.
+
+Reading text back goes through a [parser backend](backends.md).

sysml2kit-0.1.0/docs/quickstart.md

@@ -0,0 +1,44 @@
+# Quickstart
+
+Build a model, run the traceability queries, and emit both output formats.
+
+```python
+from sysml2kit import Model, builder
+from sysml2kit.query import trace_matrix, unverified_requirements
+from sysml2kit.text import write_model
+from sysml2kit.interchange import write_json
+from sysml2kit.validation import validate
+
+model = Model()
+pkg = builder.pkg(model, "Vehicle")
+battery = builder.part(model, "battery", owner=pkg)
+range_req = builder.req(
+    model, "REQ-001", "Range", owner=pkg,
+    text="The vehicle shall travel at least 400 km on one charge.",
+)
+builder.satisfy(model, source=battery, target=range_req)
+
+print(unverified_requirements(model))   # [REQ-001] - nothing verifies it yet
+print(trace_matrix(model).render())     # requirement-by-part grid
+for issue in validate(model):
+    print(issue.rule_id, issue.severity, issue.message)
+
+print(write_model(model))               # SysML v2 textual notation
+write_json(model, "vehicle.json")       # Systems Modeling API interchange
+```
+
+The same operations from the command line:
+
+```bash
+sysml2kit show vehicle.json --traceability
+sysml2kit validate vehicle.json
+sysml2kit export vehicle.json --to sysml
+```
+
+Reading `.sysml` text back requires the parse extra:
+
+```python
+from sysml2kit.backends import get_backend
+
+model = get_backend("sysmlpy").parse(open("vehicle.sysml").read())
+```

sysml2kit-0.1.0/docs/reference.md

@@ -0,0 +1,31 @@
+# API reference
+
+## Model and elements
+
+::: sysml2kit.model.container.Model
+
+::: sysml2kit.model.base
+
+## Builder
+
+::: sysml2kit.model.builder
+
+## Queries
+
+::: sysml2kit.query
+
+## Validation
+
+::: sysml2kit.validation
+
+## Diff
+
+::: sysml2kit.diff
+
+## Interop
+
+::: sysml2kit.interop.requirements
+
+## Units
+
+::: sysml2kit.units

sysml2kit-0.1.0/docs/rf-library.md

@@ -0,0 +1,33 @@
+# The RF library
+
+sysml2kit stays domain-general. Antenna/RF vocabulary lives in
+[sysml2kit-rf-library](https://github.com/jman4162/sysml2kit-rf-library):
+
+```bash
+pip install sysml2kit-rf-library
+```
+
+```python
+from sysml2kit_rf_library import load_model
+from sysml2kit.interop import extract_requirements
+from sysml2kit.query import trace_matrix
+
+model = load_model("satcom-terminal-t3001")
+print(trace_matrix(model).render())
+for spec in extract_requirements(model):
+    print(spec.id, spec.metric_key, spec.op, spec.value, spec.units)
+```
+
+It ships four library packages (RFVocabulary quantity kinds with units,
+RFParts part/port definitions, RFRequirements requirement definitions using
+the metricKey convention, RFAnalyses analysis case definitions) plus
+**SatcomTerminal28GHz** — a worked example mirroring the aedl `t3-001`
+benchmark: a 28 GHz LEO uplink phased-array terminal with eight
+machine-checkable requirements (worst-case link margin, sidelobe level,
+independent link crosscheck, clear-sky and gain agreement, prime-power and
+unit-cost ceilings, grating-lobe margin), each satisfied by a part and
+verified by an analysis.
+
+The library demonstrates the intended division of labor: domain vocabulary
+as SysML v2 model content, generic mechanics in the kit, physics engines
+downstream.

sysml2kit-0.1.0/docs/traceability.md

@@ -0,0 +1,47 @@
+# Traceability
+
+The queries in `sysml2kit.query` answer the questions a requirements-driven
+workflow actually asks:
+
+| Question | Call |
+|---|---|
+| What satisfies this requirement? | `satisfied_by(model, req)` |
+| What verifies it? | `verified_by(model, req)` |
+| What does it derive from? | `derived_from(model, req)` |
+| Which requirements have no satisfier? | `unsatisfied_requirements(model)` |
+| Which have no verifier? | `unverified_requirements(model)` |
+| What is allocated where? | `allocation_table(model)` |
+| The whole grid at once? | `trace_matrix(model).render()` |
+
+The four relationship kinds are first-class elements
+(`SatisfyRelationship`, `VerifyRelationship`, `DeriveRelationship`,
+`AllocateRelationship`) created through the builder:
+
+```python
+builder.satisfy(model, source=battery, target=mass_req)
+builder.verify(model, source=range_analysis, target=range_req)
+builder.derive(model, source=mass_req, target=range_req)
+builder.allocate(model, source=range_req, target=battery)
+```
+
+## Handing requirements to an engine: the metricKey convention
+
+A requirement usage that owns attributes `metricKey` (string), `threshold`
+(number with unit), `op` (`>=`, `<=`, `==`, `>`, `<`), and optionally
+`severity` (`must`/`should`/`nice`) is machine-checkable.
+`sysml2kit.interop.extract_requirements` turns each into a `RequirementSpec`
+carrying the threshold in both operator form (`op` + `value`) and bound form
+(`minimum`/`maximum`), plus the satisfy/verify trace as qualified names:
+
+```python
+from sysml2kit.interop import extract_requirements
+
+for spec in extract_requirements(model):
+    print(spec.id, spec.metric_key, spec.op, spec.value, spec.satisfied_by)
+```
+
+Both forms are always populated (`>= 40` also sets `minimum=40`), so an
+operator-style requirements engine (phased-array-systems) and a bound-style
+one (aedl) each need only a small adapter, which lives in those packages.
+The metric key names the entry in the engine's metrics dict; the model never
+computes anything itself.

{sysml2kit-0.0.1 → sysml2kit-0.1.0}/mkdocs.yml

@@ -31,3 +31,12 @@ plugins:
 
 nav:
   - Home: index.md
+  - Quickstart: quickstart.md
+  - Concepts: concepts.md
+  - Traceability: traceability.md
+  - Interchange: interchange.md
+  - Command line: cli.md
+  - API client: api-client.md
+  - Parser backends: backends.md
+  - RF library: rf-library.md
+  - Reference: reference.md

{sysml2kit-0.0.1 → sysml2kit-0.1.0}/src/sysml2kit/__init__.py

@@ -1,14 +1,16 @@
 """API-first Python tooling for building, querying, validating, and automating SysML v2 models.
 
-The 0.0.x releases are a published skeleton; the object model, writer, and
-queries land in 0.1.0. See https://github.com/jman4162/sysml2kit.
+See https://github.com/jman4162/sysml2kit and SPEC.md for the element subset
+(the "pragmatic profile") and the pinned spec release.
 """
 
 from importlib.metadata import PackageNotFoundError, version
 
+from sysml2kit.model import Model, builder
+
 try:
     __version__ = version("sysml2kit")
 except PackageNotFoundError:  # running from a source tree without an install
     __version__ = "0.0.0.dev0"
 
-__all__ = ["__version__"]
+__all__ = ["Model", "__version__", "builder"]

{sysml2kit-0.0.1 → sysml2kit-0.1.0}/src/sysml2kit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.1'
-__version_tuple__ = version_tuple = (0, 0, 1)
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
 
 __commit_id__ = commit_id = None

sysml2kit-0.1.0/src/sysml2kit/api/__init__.py

@@ -0,0 +1,7 @@
+"""HTTP client for the OMG Systems Modeling API and Services."""
+
+from sysml2kit.api.client import SysMLApiClient
+from sysml2kit.api.errors import ApiError
+from sysml2kit.api.models import Branch, Commit, Project
+
+__all__ = ["ApiError", "Branch", "Commit", "Project", "SysMLApiClient"]

sysml2kit-0.1.0/src/sysml2kit/api/client.py

@@ -0,0 +1,120 @@
+"""A thin, hand-written client for the OMG Systems Modeling API.
+
+Covers the read paths (projects, branches, commits, elements) plus creating
+a project and pushing a model as a commit. Hand-written on purpose: the
+official generated Python client is LGPL and unmaintained; this one is a few
+hundred lines against the REST/JSON binding and returns sysml2kit models.
+"""
+
+from __future__ import annotations
+
+import types
+from typing import Any, Self
+
+import httpx
+
+from sysml2kit.interchange import model_from_json, model_to_json
+from sysml2kit.model.container import Model
+
+from .errors import ApiError
+from .models import Branch, Commit, Project
+
+
+class SysMLApiClient:
+    """Synchronous client; use as a context manager to reuse one connection."""
+
+    def __init__(self, base_url: str, *, token: str | None = None, timeout: float = 30.0) -> None:
+        headers = {"Accept": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(base_url=base_url.rstrip("/"), headers=headers, timeout=timeout)
+
+    # ------------------------------------------------------------- lifecycle
+    def close(self) -> None:
+        """Close the underlying connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # ------------------------------------------------------------- plumbing
+    def _get(self, path: str) -> Any:
+        response = self._client.get(path)
+        if response.status_code >= 400:
+            raise ApiError(response.status_code, response.text)
+        return response.json()
+
+    def _post(self, path: str, payload: Any) -> Any:
+        response = self._client.post(path, json=payload)
+        if response.status_code >= 400:
+            raise ApiError(response.status_code, response.text)
+        return response.json()
+
+    # ---------------------------------------------------------------- reads
+    def list_projects(self) -> list[Project]:
+        """List projects on the server."""
+        return [Project.model_validate(item) for item in self._get("/projects")]
+
+    def get_project(self, project_id: str) -> Project:
+        """Fetch one project."""
+        return Project.model_validate(self._get(f"/projects/{project_id}"))
+
+    def list_branches(self, project_id: str) -> list[Branch]:
+        """List a project's branches."""
+        return [
+            Branch.model_validate(item) for item in self._get(f"/projects/{project_id}/branches")
+        ]
+
+    def list_commits(self, project_id: str) -> list[Commit]:
+        """List a project's commits."""
+        return [
+            Commit.model_validate(item) for item in self._get(f"/projects/{project_id}/commits")
+        ]
+
+    def get_commit(self, project_id: str, commit_id: str) -> Commit:
+        """Fetch one commit."""
+        return Commit.model_validate(self._get(f"/projects/{project_id}/commits/{commit_id}"))
+
+    def get_element(self, project_id: str, commit_id: str, element_id: str) -> dict[str, Any]:
+        """Fetch one element's raw interchange record."""
+        record = self._get(f"/projects/{project_id}/commits/{commit_id}/elements/{element_id}")
+        return dict(record)
+
+    def list_elements(self, project_id: str, commit_id: str) -> Model:
+        """Fetch every element at a commit and build a Model from them."""
+        records = self._get(f"/projects/{project_id}/commits/{commit_id}/elements")
+        return model_from_json(records)
+
+    # --------------------------------------------------------------- writes
+    def create_project(self, name: str, *, description: str | None = None) -> Project:
+        """Create a project."""
+        payload: dict[str, Any] = {"@type": "Project", "name": name}
+        if description:
+            payload["description"] = description
+        return Project.model_validate(self._post("/projects", payload))
+
+    def push_model(
+        self,
+        project_id: str,
+        model: Model,
+        *,
+        branch: str | None = None,
+        message: str | None = None,
+    ) -> Commit:
+        """Create a commit whose change set inserts every element of the model."""
+        change = [{"@type": "DataVersion", "payload": record} for record in model_to_json(model)]
+        payload: dict[str, Any] = {"@type": "Commit", "change": change}
+        if message:
+            payload["description"] = message
+        path = f"/projects/{project_id}/commits"
+        if branch:
+            path += f"?branchId={branch}"
+        return Commit.model_validate(self._post(path, payload))

sysml2kit-0.1.0/src/sysml2kit/api/errors.py

@@ -0,0 +1,12 @@
+"""API client errors."""
+
+from __future__ import annotations
+
+
+class ApiError(RuntimeError):
+    """A Systems Modeling API request failed."""
+
+    def __init__(self, status: int, detail: str) -> None:
+        super().__init__(f"HTTP {status}: {detail}")
+        self.status = status
+        self.detail = detail

sysml2kit-0.1.0/src/sysml2kit/api/models.py

@@ -0,0 +1,36 @@
+"""Resource models for the Systems Modeling API."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Project(BaseModel):
+    """A model repository project."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(alias="@id")
+    name: str | None = None
+    description: str | None = None
+
+
+class Branch(BaseModel):
+    """A branch within a project."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(alias="@id")
+    name: str | None = None
+    head: str | None = None
+
+
+class Commit(BaseModel):
+    """A commit within a project."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(alias="@id")
+    description: str | None = None
+    created: str | None = None
+    owning_project: str | None = None