treedx 0.1.1__tar.gz

treedx-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+/packages/trsd-sdk
+/target
+**/_build
+**/deps
+**/priv/native
+**/.elixir_ls
+/tools/treedx_profiler/treedx_profiler
+repomix-snapshot.xml

treedx-0.1.1/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: treedx
+Version: 0.1.1
+Summary: Generic Python SDK for TreeDX.
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TreeDX Python SDK
+
+`treedx` is the generic Python SDK for TreeDX. It implements the shared
+`packages/sdk-spec` architecture, follows `docs/api/openapi.yaml`, and does not
+encode TreeSeed product semantics. `packages/trsd-sdk` is a downstream
+TreeSeed consumer/reference only.
+
+The current `sdk-manifest.yaml` reports modules, capabilities, and test roots as
+`implemented`. The SDK exposes all 113 `/api/v1` OpenAPI operations through
+first-class module methods and a validated raw operation fallback.
+
+## Install
+
+```bash
+python -m pip install treedx
+```
+
+## Configure Client
+
+```python
+from treedx import TreeDxClient, TreeDxApiError
+
+client = TreeDxClient(
+    base_url="http://localhost:4000",
+    token="...",
+)
+```
+
+The client also accepts an auth provider, custom transport, default headers, and
+timeout settings.
+
+## Authenticate
+
+Bearer authentication uses the `Authorization: Bearer <token>` header. Tokens
+may come from `token` or an auth provider. The SDK must not place production
+identity in request JSON and must not log bearer tokens.
+
+## Basic Health Call
+
+```python
+health = client.health()
+version = client.version()
+```
+
+## Repository Query
+
+Repository-scoped query helpers live under `client.query`:
+
+```python
+results = client.query.search_files(
+    "repo_demo",
+    {"query": "release provenance", "paths": ["docs/**"]},
+)
+
+file = client.query.read_file(
+    "repo_demo",
+    {"ref": "refs/heads/main", "path": "docs/index.md"},
+)
+```
+
+## Workspace File Lifecycle
+
+Workspace-scoped file helpers live under `client.workspaces` and `client.files`:
+
+```python
+workspace = client.workspaces.create("repo_demo", {"ref": "refs/heads/main"})
+
+client.files.write("workspace_123", {"path": "docs/new.md", "content": "# New"})
+client.files.patch("workspace_123", {"path": "docs/new.md", "patch": "..."})
+client.files.commit("workspace_123", {"message": "Update docs"})
+client.workspaces.close("workspace_123")
+```
+
+## Blob Upload And Download
+
+Binary helpers preserve byte payloads and reject strings as binary input.
+
+```python
+client.blobs.upload("workspace_123", b"\x01\x02\x03")
+blob = client.blobs.download("workspace_123", {"path": "asset.bin"})
+```
+
+Multipart helpers expose create, part upload, complete, and abort:
+
+```python
+upload = client.blobs.create_multipart_upload("workspace_123", {"path": "large.bin"})
+client.blobs.upload_part("workspace_123", upload["uploadId"], 1, b"\x01")
+client.blobs.complete_multipart_upload(
+    "workspace_123",
+    upload["uploadId"],
+    {"parts": [{"partNumber": 1}]},
+)
+```
+
+## Graph And Context Query
+
+```python
+client.graph.refresh("repo_demo")
+graph = client.graph.query("repo_demo", {"query": "MATCH ..."})
+context = client.context.build("repo_demo", {"query": "ctx docs"})
+parsed = client.context.parse("repo_demo", {"source": "ctx docs"})
+```
+
+## Federated Query
+
+Federation helpers use portfolio/global TreeDX routes rather than a single
+configured repository:
+
+```python
+plan = client.federation.plan({"query": "release provenance"})
+results = client.federation.search({"query": "release provenance"})
+```
+
+## Scoped Admin And Internal Modules
+
+Full OpenAPI coverage includes sensitive scoped modules: Admin, Audit, Policy,
+SearchIndex, and FederationInternal. These APIs require appropriate TreeDX
+credentials and should be used carefully against production systems. They remain
+generic TreeDX APIs and do not encode TreeSeed product semantics.
+
+The raw operation fallback validates method/path pairs against generated OpenAPI
+metadata before dispatch.
+
+## Error Handling
+
+Non-2xx responses and network failures raise `TreeDxApiError`. The error keeps
+`status`, `code`, `message`, `details`, and `payload` available. Network
+failures use `status=0` and `code="network_error"`.
+
+```python
+try:
+    client.whoami()
+except TreeDxApiError as error:
+    print(error.status, error.code, error.message)
+```
+
+## Pagination
+
+`TreeDxPage` and `TreeDxCursor` model opaque server-owned cursor pagination.
+Helpers preserve cursor metadata and do not decode cursor internals.
+
+## Binary And Multipart
+
+Binary helpers accept `bytes`, `bytearray`, `memoryview`, and binary streams.
+Multipart helper metadata is represented by `MultipartUpload`.
+
+## Conformance
+
+The conformance adapter loads Phase 7 scenario records and reports
+`live or configured` until executable live dispatch is wired. It must not fake
+conformance success.
+
+```bash
+python -m pytest tests/conformance
+```
+
+## Integration
+
+Integration tests call a live TreeDX server only when `TREEDX_BASE_URL` is set.
+Without that environment variable, they skip cleanly.
+
+```bash
+python -m pytest tests/integration
+```
+
+## Development Commands
+
+```bash
+python -m pip install -e ".[dev]"
+python scripts/check_treedx_generated_types.py
+python -m build
+python -m pytest tests/conformance
+python -m pytest tests/integration
+python -m pytest
+```

treedx-0.1.1/README.md

@@ -0,0 +1,175 @@
+# TreeDX Python SDK
+
+`treedx` is the generic Python SDK for TreeDX. It implements the shared
+`packages/sdk-spec` architecture, follows `docs/api/openapi.yaml`, and does not
+encode TreeSeed product semantics. `packages/trsd-sdk` is a downstream
+TreeSeed consumer/reference only.
+
+The current `sdk-manifest.yaml` reports modules, capabilities, and test roots as
+`implemented`. The SDK exposes all 113 `/api/v1` OpenAPI operations through
+first-class module methods and a validated raw operation fallback.
+
+## Install
+
+```bash
+python -m pip install treedx
+```
+
+## Configure Client
+
+```python
+from treedx import TreeDxClient, TreeDxApiError
+
+client = TreeDxClient(
+    base_url="http://localhost:4000",
+    token="...",
+)
+```
+
+The client also accepts an auth provider, custom transport, default headers, and
+timeout settings.
+
+## Authenticate
+
+Bearer authentication uses the `Authorization: Bearer <token>` header. Tokens
+may come from `token` or an auth provider. The SDK must not place production
+identity in request JSON and must not log bearer tokens.
+
+## Basic Health Call
+
+```python
+health = client.health()
+version = client.version()
+```
+
+## Repository Query
+
+Repository-scoped query helpers live under `client.query`:
+
+```python
+results = client.query.search_files(
+    "repo_demo",
+    {"query": "release provenance", "paths": ["docs/**"]},
+)
+
+file = client.query.read_file(
+    "repo_demo",
+    {"ref": "refs/heads/main", "path": "docs/index.md"},
+)
+```
+
+## Workspace File Lifecycle
+
+Workspace-scoped file helpers live under `client.workspaces` and `client.files`:
+
+```python
+workspace = client.workspaces.create("repo_demo", {"ref": "refs/heads/main"})
+
+client.files.write("workspace_123", {"path": "docs/new.md", "content": "# New"})
+client.files.patch("workspace_123", {"path": "docs/new.md", "patch": "..."})
+client.files.commit("workspace_123", {"message": "Update docs"})
+client.workspaces.close("workspace_123")
+```
+
+## Blob Upload And Download
+
+Binary helpers preserve byte payloads and reject strings as binary input.
+
+```python
+client.blobs.upload("workspace_123", b"\x01\x02\x03")
+blob = client.blobs.download("workspace_123", {"path": "asset.bin"})
+```
+
+Multipart helpers expose create, part upload, complete, and abort:
+
+```python
+upload = client.blobs.create_multipart_upload("workspace_123", {"path": "large.bin"})
+client.blobs.upload_part("workspace_123", upload["uploadId"], 1, b"\x01")
+client.blobs.complete_multipart_upload(
+    "workspace_123",
+    upload["uploadId"],
+    {"parts": [{"partNumber": 1}]},
+)
+```
+
+## Graph And Context Query
+
+```python
+client.graph.refresh("repo_demo")
+graph = client.graph.query("repo_demo", {"query": "MATCH ..."})
+context = client.context.build("repo_demo", {"query": "ctx docs"})
+parsed = client.context.parse("repo_demo", {"source": "ctx docs"})
+```
+
+## Federated Query
+
+Federation helpers use portfolio/global TreeDX routes rather than a single
+configured repository:
+
+```python
+plan = client.federation.plan({"query": "release provenance"})
+results = client.federation.search({"query": "release provenance"})
+```
+
+## Scoped Admin And Internal Modules
+
+Full OpenAPI coverage includes sensitive scoped modules: Admin, Audit, Policy,
+SearchIndex, and FederationInternal. These APIs require appropriate TreeDX
+credentials and should be used carefully against production systems. They remain
+generic TreeDX APIs and do not encode TreeSeed product semantics.
+
+The raw operation fallback validates method/path pairs against generated OpenAPI
+metadata before dispatch.
+
+## Error Handling
+
+Non-2xx responses and network failures raise `TreeDxApiError`. The error keeps
+`status`, `code`, `message`, `details`, and `payload` available. Network
+failures use `status=0` and `code="network_error"`.
+
+```python
+try:
+    client.whoami()
+except TreeDxApiError as error:
+    print(error.status, error.code, error.message)
+```
+
+## Pagination
+
+`TreeDxPage` and `TreeDxCursor` model opaque server-owned cursor pagination.
+Helpers preserve cursor metadata and do not decode cursor internals.
+
+## Binary And Multipart
+
+Binary helpers accept `bytes`, `bytearray`, `memoryview`, and binary streams.
+Multipart helper metadata is represented by `MultipartUpload`.
+
+## Conformance
+
+The conformance adapter loads Phase 7 scenario records and reports
+`live or configured` until executable live dispatch is wired. It must not fake
+conformance success.
+
+```bash
+python -m pytest tests/conformance
+```
+
+## Integration
+
+Integration tests call a live TreeDX server only when `TREEDX_BASE_URL` is set.
+Without that environment variable, they skip cleanly.
+
+```bash
+python -m pytest tests/integration
+```
+
+## Development Commands
+
+```bash
+python -m pip install -e ".[dev]"
+python scripts/check_treedx_generated_types.py
+python -m build
+python -m pytest tests/conformance
+python -m pytest tests/integration
+python -m pytest
+```

treedx-0.1.1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "treedx"
+version = "0.1.1"
+description = "Generic Python SDK for TreeDX."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = [
+  "httpx>=0.28,<1",
+  "PyYAML>=6.0,<7"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9",
+  "build>=1.2,<2"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/treedx"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

treedx-0.1.1/scripts/check_treedx_generated_types.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from generate_treedx_openapi_types import OUTPUT_PATH, render_openapi_types
+
+
+def main() -> None:
+    expected = render_openapi_types()
+    actual = OUTPUT_PATH.read_text(encoding="utf8") if OUTPUT_PATH.exists() else ""
+    if actual != expected:
+        print("TreeDX generated OpenAPI metadata is stale. Run scripts/generate_treedx_openapi_types.py.", file=sys.stderr)
+        raise SystemExit(1)
+    print("TreeDX generated OpenAPI metadata is fresh")
+
+
+if __name__ == "__main__":
+    main()

treedx-0.1.1/scripts/generate_treedx_openapi_types.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+REPO_ROOT = PACKAGE_ROOT.parents[1]
+OPENAPI_PATH = REPO_ROOT / "docs" / "api" / "openapi.yaml"
+OUTPUT_PATH = PACKAGE_ROOT / "src" / "treedx" / "generated" / "openapi_types.py"
+
+
+def render_openapi_types() -> str:
+    operation_keys: set[tuple[str, str]] = set()
+    current_path: str | None = None
+    in_paths = False
+    for line in OPENAPI_PATH.read_text(encoding="utf8").splitlines():
+        if line == "paths:":
+            in_paths = True
+            continue
+        if in_paths and line and not line.startswith(" "):
+            break
+        if not in_paths:
+            continue
+        path_match = re.match(r"^  (/api/v1/[^:]+):\s*$", line)
+        if path_match:
+            current_path = path_match.group(1)
+            continue
+        method_match = re.match(r"^    (get|post|put|patch|delete):\s*$", line)
+        if current_path and method_match:
+            operation_keys.add((method_match.group(1).upper(), current_path))
+    operations = [{"method": method, "path": path} for method, path in operation_keys]
+    operations.sort(key=lambda operation: f"{operation['method']} {operation['path']}")
+    rendered_operations = ",\n".join(
+        f"    {{\"method\": \"{operation['method']}\", \"path\": \"{operation['path']}\"}}"
+        for operation in operations
+    )
+    return (
+        "# Generated by scripts/generate_treedx_openapi_types.py. Do not edit by hand.\n\n"
+        "from typing import Final, Literal, TypedDict\n\n\n"
+        "TreeDxOpenApiMethod = Literal[\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"]\n\n\n"
+        "class TreeDxOpenApiOperation(TypedDict):\n"
+        "    method: TreeDxOpenApiMethod\n"
+        "    path: str\n\n\n"
+        f"TREEDX_OPENAPI_OPERATION_COUNT: Final[int] = {len(operations)}\n\n"
+        "TREEDX_OPENAPI_OPERATIONS: Final[tuple[TreeDxOpenApiOperation, ...]] = (\n"
+        f"{rendered_operations}\n"
+        ")\n"
+    )
+
+
+def main() -> None:
+    OUTPUT_PATH.write_text(render_openapi_types(), encoding="utf8")
+
+
+if __name__ == "__main__":
+    main()

treedx-0.1.1/sdk-manifest.yaml

@@ -0,0 +1,64 @@
+sdk: treedx-python
+language: python
+version: 0.1.1
+sdkSpecVersion: 0.1.0
+openapiVersion: 0.10.0
+testLayout:
+  unit: implemented
+  adapters: implemented
+  generated: implemented
+  conformance: implemented
+  integration: implemented
+modules:
+  Client: implemented
+  Auth: implemented
+  Repositories: implemented
+  Workspaces: implemented
+  Files: implemented
+  Blobs: implemented
+  Query: implemented
+  Graph: implemented
+  Context: implemented
+  Federation: implemented
+  FederationInternal: implemented
+  Registry: implemented
+  Snapshots: implemented
+  Artifacts: implemented
+  Mirrors: implemented
+  Migrations: implemented
+  Exec: implemented
+  Observability: implemented
+  Admin: implemented
+  Audit: implemented
+  Policy: implemented
+  SearchIndex: implemented
+capabilities:
+  health.basic: implemented
+  auth.whoami: implemented
+  auth.mode_dev_token: implemented
+  repositories.lifecycle: implemented
+  repositories.push_sync: implemented
+  workspaces.lifecycle: implemented
+  files.lifecycle: implemented
+  blobs.binary: implemented
+  blobs.multipart: implemented
+  query.repository: implemented
+  graph.repository: implemented
+  graph.expanded_repository: implemented
+  context.repository: implemented
+  federation.global_query: implemented
+  federation.catalog_peers_routes: implemented
+  federation.internal_node_operations: implemented
+  registry.routing: implemented
+  snapshots.lifecycle: implemented
+  artifacts.lifecycle: implemented
+  mirrors.lifecycle: implemented
+  migrations.lifecycle: implemented
+  exec.workspace: implemented
+  observability.health_metrics: implemented
+  admin.storage_operations: implemented
+  admin.repository_operations: implemented
+  admin.workspace_artifact_operations: implemented
+  audit.events: implemented
+  policy.capabilities_grants: implemented
+  search_index.lifecycle: implemented

treedx-0.1.1/src/treedx/__init__.py

@@ -0,0 +1,17 @@
+from .binary import BinaryBody, MultipartUpload
+from .client import TreeDxClient, TreeDxFederatedClient, TreeDxRegistryClient
+from .config import TreeDxClientConfig
+from .errors import TreeDxApiError
+from .pagination import TreeDxCursor, TreeDxPage
+
+__all__ = [
+    "BinaryBody",
+    "MultipartUpload",
+    "TreeDxApiError",
+    "TreeDxClient",
+    "TreeDxClientConfig",
+    "TreeDxCursor",
+    "TreeDxFederatedClient",
+    "TreeDxPage",
+    "TreeDxRegistryClient",
+]

treedx-0.1.1/src/treedx/adapters/__init__.py

@@ -0,0 +1,43 @@
+from .federation_internal import FederationInternalAdapter
+from .search_index import SearchIndexAdapter
+from .policy import PolicyAdapter
+from .audit import AuditAdapter
+from .admin import AdminAdapter
+from .artifacts import ArtifactsAdapter
+from .blobs import BlobsAdapter
+from .context import ContextAdapter
+from .exec import ExecAdapter
+from .federation import FederationAdapter
+from .files import FilesAdapter
+from .graph import GraphAdapter
+from .migrations import MigrationsAdapter
+from .mirrors import MirrorsAdapter
+from .observability import ObservabilityAdapter
+from .query import QueryAdapter
+from .registry import RegistryAdapter
+from .repositories import RepositoriesAdapter
+from .snapshots import SnapshotsAdapter
+from .workspaces import WorkspacesAdapter
+
+__all__ = [
+    "FederationInternalAdapter",
+    "SearchIndexAdapter",
+    "PolicyAdapter",
+    "AuditAdapter",
+    "AdminAdapter",
+    "ArtifactsAdapter",
+    "BlobsAdapter",
+    "ContextAdapter",
+    "ExecAdapter",
+    "FederationAdapter",
+    "FilesAdapter",
+    "GraphAdapter",
+    "MigrationsAdapter",
+    "MirrorsAdapter",
+    "ObservabilityAdapter",
+    "QueryAdapter",
+    "RegistryAdapter",
+    "RepositoriesAdapter",
+    "SnapshotsAdapter",
+    "WorkspacesAdapter",
+]

treedx-0.1.1/src/treedx/adapters/admin.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .common import json_request
+from treedx.transport import Transport
+
+
+class AdminAdapter:
+    def __init__(self, transport: Transport) -> None:
+        self.transport = transport
+
+    def deep_health(self) -> Any: return json_request(self.transport, "GET", "/api/v1/admin/health/deep")
+    def storage_health(self) -> Any: return json_request(self.transport, "GET", "/api/v1/admin/storage/health")
+    def storage_check(self, body: Any | None = None) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/check", body)
+    def storage_recover(self, body: Any | None = None) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/recover", body)
+    def storage_compact(self, body: Any | None = None) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/compact", body)
+    def storage_backup(self, body: Any | None = None) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/backup", body)
+    def storage_migrations(self) -> Any: return json_request(self.transport, "GET", "/api/v1/admin/storage/migrations")
+    def storage_migration_plan(self, body: Any) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/migrations/plan", body)
+    def storage_migration_apply(self, body: Any) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/migrations/apply", body)
+    def storage_migration_rollback(self, body: Any) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/migrations/rollback", body)
+    def storage_restore_verify(self, body: Any) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/restore/verify", body)
+    def storage_restore(self, body: Any) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/storage/restore", body)
+    def quarantined_workspaces(self) -> Any: return json_request(self.transport, "GET", "/api/v1/admin/workspaces/quarantined")
+    def cleanup_artifacts(self, body: Any | None = None) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/artifacts/cleanup", body)
+    def import_local_repo(self, body: Any) -> Any: return json_request(self.transport, "POST", "/api/v1/admin/repos/import-local", body)

treedx-0.1.1/src/treedx/adapters/artifacts.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .common import json_request, segment
+from treedx.transport import Transport
+
+
+class ArtifactsAdapter:
+    def __init__(self, transport: Transport) -> None:
+        self.transport = transport
+
+    def export(self, repo_id: str, body: Any) -> Any:
+        return json_request(self.transport, "POST", f"/api/v1/repos/{segment(repo_id)}/artifacts/export", body)
+
+    def list(self, repo_id: str) -> Any:
+        return json_request(self.transport, "GET", f"/api/v1/repos/{segment(repo_id)}/artifacts")
+
+    def get(self, repo_id: str, artifact_id: str) -> Any:
+        return json_request(self.transport, "GET", f"/api/v1/repos/{segment(repo_id)}/artifacts/{segment(artifact_id)}")
+
+    def delete(self, repo_id: str, artifact_id: str) -> Any:
+        return json_request(self.transport, "DELETE", f"/api/v1/repos/{segment(repo_id)}/artifacts/{segment(artifact_id)}")

treedx-0.1.1/src/treedx/adapters/audit.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .common import json_request
+from treedx.transport import Transport
+
+
+class AuditAdapter:
+    def __init__(self, transport: Transport) -> None:
+        self.transport = transport
+
+    def events(self, query: Mapping[str, str | int | float | bool | None] | None = None) -> Any:
+        return json_request(self.transport, "GET", "/api/v1/audit/events", query=query)