tropek-client 0.1.1a0__tar.gz

tropek_client-0.1.1a0/.gitignore

@@ -0,0 +1,186 @@
+# Claude Code local settings (personal paths, hooks)
+.claude/settings.local.json
+
+# Superpowers brainstorming sessions
+.superpowers/
+
+# Personal docs (research, design inspiration, old specs)
+docs/personal/
+
+# Git worktrees
+.worktrees/
+
+# Dev output (logs, artifacts)
+out/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+!ui/src/lib/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+# .python-version
+
+# UV
+#uv.lock
+
+# poetry
+#poetry.lock
+#poetry.toml
+
+# pdm
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#pixi.lock
+.pixi
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# IDEs
+.idea/
+.vscode/
+*.iml
+
+# Cursor
+.cursorignore
+.cursorindexingignore
+
+# Generated mock adapter data
+adapters/mock/data/*/metrics.csv
+
+# Node / React UI
+node_modules/
+ui/dist/
+ui/.vite/
+
+.tmp

tropek_client-0.1.1a0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: tropek-client
+Version: 0.1.1a0
+Summary: Typed Python client for the TROPEK quality gate API
+Requires-Python: >=3.13
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0

tropek_client-0.1.1a0/README.md

@@ -0,0 +1,350 @@
+# TROPEK Python Client
+
+Typed Python client and CLI for the TROPEK quality gate API. Provides a programmatic
+interface to all TROPEK resources and a declarative YAML manifest system for
+infrastructure-as-code workflows.
+
+## Installation
+
+Requires Python 3.13+. Install from the local package:
+
+```bash
+cd clients/python
+uv pip install -e .
+```
+
+Dependencies: `httpx`, `pydantic`, `pyyaml`, `click`.
+
+## Quick Start
+
+```python
+from tropek_client import TropekClient
+
+with TropekClient('http://localhost:8080', api_key='my-key') as client:
+    # Check connectivity
+    client.health()
+
+    # Create an asset and trigger an evaluation
+    client.assets.create('web-api', type_name='service', tags={'env': 'prod'})
+    result = client.evaluations.evaluate(
+        asset_name='web-api',
+        eval_name='release-42',
+        period_start='2024-01-01T00:00:00Z',
+        period_end='2024-01-01T01:00:00Z',
+    )
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | (required) | TROPEK API base URL |
+| `api_key` | `None` | Bearer token for authentication |
+
+The client uses a 30-second timeout. The underlying `httpx.Client` is closed
+automatically when using the context manager.
+
+## Client API Reference
+
+The client exposes resource-specific namespaces as attributes on `TropekClient`.
+
+### `client.health() -> dict`
+
+Returns API health status.
+
+### Asset Types — `client.asset_types`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `list[AssetType]` | List all asset types |
+| `create(name, *, is_default=False)` | `AssetType` | Create an asset type |
+| `set_default(name)` | `AssetType` | Set a type as default |
+| `rename(name, new_name)` | `AssetType` | Rename a type |
+| `delete(name)` | `None` | Delete a type |
+
+### Assets — `client.assets`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list(*, type_name=, tag_key=, tag_val=)` | `PagedResponse[Asset]` | List with optional filters |
+| `create(name, type_name='vm', *, display_name=, tags=, variables=)` | `Asset` | Create an asset |
+| `get(name)` | `Asset` | Get by name |
+| `update(name, **kwargs)` | `Asset` | Partial update |
+| `delete(name)` | `None` | Delete an asset |
+| `tag_keys()` | `list[dict]` | Distinct tag keys with counts |
+| `tag_values(key)` | `list[dict]` | Values for a tag key |
+
+### Asset Groups — `client.asset_groups`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `PagedResponse[AssetGroup]` | List all groups |
+| `tree()` | `AssetGroupTree` | Get hierarchical tree |
+| `create(name, *, display_name=, members=, subgroups=)` | `AssetGroup` | Create a group |
+| `get(name)` | `AssetGroup` | Get by name |
+| `add_member(group_name, asset_id, weight=1.0)` | `AssetGroup` | Add asset to group |
+| `remove_member(group_name, asset_id)` | `None` | Remove asset from group |
+| `add_subgroup(group_name, child_group_id, weight=1.0)` | `AssetGroup` | Nest a group |
+| `remove_subgroup(group_name, child_group_id)` | `None` | Remove nested group |
+
+### Data Sources — `client.datasources`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list(*, adapter_type=)` | `PagedResponse[DataSource]` | List with optional filter |
+| `create(name, adapter_type, adapter_url, **kwargs)` | `DataSource` | Register a datasource |
+| `get(name)` | `DataSource` | Get by name |
+| `update(name, **kwargs)` | `DataSource` | Partial update |
+| `delete(name)` | `None` | Delete a datasource |
+| `tag_keys()` | `list[dict]` | Distinct tag keys |
+| `tag_values(key)` | `list[dict]` | Values for a tag key |
+
+### SLI Definitions — `client.slis`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `PagedResponse[SLIDefinition]` | List all SLIs |
+| `create(body)` | `SLIDefinition` | Create (or new version) |
+| `get(name)` | `SLIDefinition` | Get latest version |
+| `versions(name)` | `list[SLIDefinition]` | All versions |
+| `delete(name)` | `None` | Delete an SLI |
+| `new_version(name, **overrides)` | `SLIDefinition` | Create new version with overrides |
+| `tag_keys()` | `list[dict]` | Distinct tag keys |
+| `tag_values(key)` | `list[dict]` | Values for a tag key |
+
+### SLO Definitions — `client.slos`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list()` | `PagedResponse[SLODefinition]` | List all SLOs |
+| `create(body)` | `SLODefinition` | Create (or new version) |
+| `get(name)` | `SLODefinition` | Get latest version |
+| `versions(name)` | `list[SLODefinition]` | All versions |
+| `delete(name)` | `None` | Delete an SLO |
+| `new_version(name, **overrides)` | `SLODefinition` | Create new version with overrides |
+| `validate(body)` | `SLOValidationResult` | Validate without saving |
+| `test(body)` | `SLOTestResult` | Dry-run evaluation |
+| `tag_keys()` | `list[dict]` | Distinct tag keys |
+| `tag_values(key)` | `list[dict]` | Values for a tag key |
+
+### SLO Assignments — `client.slo_assignments`
+
+Pins an asset or group to a specific SLO definition version + datasource.
+
+| Method | Returns | Description |
+|---|---|---|
+| `create_for_asset(asset_name, slo_definition_id, data_source_name, *, comparison_rules=)` | `SLOAssignment` | Upsert for asset |
+| `create_for_group(group_name, slo_definition_id, data_source_name, *, comparison_rules=)` | `SLOAssignment` | Upsert for group |
+| `list_for_asset(asset_name)` | `list[SLOAssignment]` | List for asset |
+| `list_for_group(group_name)` | `list[SLOAssignment]` | List for group |
+| `delete_for_asset(asset_name, slo_definition_id)` | `None` | Delete for asset |
+| `delete_for_group(group_name, slo_definition_id)` | `None` | Delete for group |
+
+### SLO Groups — `client.slo_groups`
+
+Template-based SLO generation with variable expansion.
+
+| Method | Returns | Description |
+|---|---|---|
+| `create(name, template_slo_name, template_slo_version, gen_variables, *, display_name=, tags=, author=)` | `SLOGroup` | Create a group |
+| `get(name)` | `SLOGroup` | Get by name |
+| `list(*, tag_key=, tag_val=)` | `list[SLOGroup]` | List with optional filters |
+| `update(name, *, template_slo_name=, template_slo_version=, gen_variables=, ...)` | `SLOGroup` | Update (triggers regeneration) |
+| `delete(name)` | `None` | Deactivate a group |
+| `extract(group_name, slo_name, new_name)` | `None` | Extract generated SLO to standalone |
+
+### SLO Group Assignments — `client.slo_group_assignments`
+
+Asset/group to SLO group with always-latest semantics.
+
+| Method | Returns | Description |
+|---|---|---|
+| `create_for_asset(asset_name, slo_group_name, data_source_name)` | `SLOGroupAssignment` | Upsert for asset |
+| `create_for_group(group_name, slo_group_name, data_source_name)` | `SLOGroupAssignment` | Upsert for group |
+| `list_for_asset(asset_name)` | `list[SLOGroupAssignment]` | List for asset |
+| `list_for_group(group_name)` | `list[SLOGroupAssignment]` | List for group |
+| `delete_for_asset(asset_name, slo_group_name)` | `None` | Delete for asset |
+| `delete_for_group(group_name, slo_group_name)` | `None` | Delete for group |
+
+### Evaluations — `client.evaluations`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list(*, asset_name=, slo_name=, result=, date=, group_name=, from_=, to=, limit=50, offset=0)` | `PagedResponse[EvaluationSummary]` | List with filters |
+| `get(eval_id)` | `EvaluationDetail` | Full evaluation detail |
+| `evaluate(asset_name, eval_name, period_start, period_end, *, variables=)` | `dict` | Trigger evaluation |
+| `evaluate_batch(mode, eval_name, *, asset_name=, periods=, asset_names=, period_start=, period_end=, variables=)` | `dict` | Batch trigger (`by_date` or `by_asset`) |
+| `invalidate(eval_id, note)` | `EvaluationSummary` | Invalidate an evaluation |
+| `restore(eval_id)` | `EvaluationSummary` | Restore invalidated eval |
+| `pin_baseline(eval_id, reason, author)` | `EvaluationDetail` | Pin as baseline |
+| `unpin_baseline(eval_id)` | `EvaluationDetail` | Remove baseline pin |
+| `override_status(eval_id, new_result, reason, author)` | `EvaluationDetail` | Override result |
+| `restore_override(eval_id)` | `EvaluationDetail` | Restore original result |
+| `re_evaluate_from_date(scope, from_date, *, selector=, slo_version=, dry_run=, pin_strategy=)` | `dict` | Re-evaluate from date |
+| `re_evaluate_from_baseline(scope, *, selector=, slo_version=, dry_run=, pin_strategy=)` | `dict` | Re-evaluate from pinned baseline |
+| `re_evaluate_from_evaluation(evaluation_id, scope, *, selector=, slo_version=, dry_run=, pin_strategy=)` | `dict` | Re-evaluate from reference eval |
+
+Re-evaluation `scope` is `{'kind': 'asset', 'asset_name': '...'}` or
+`{'kind': 'group', 'group_name': '...'}`. `pin_strategy` can be `'skip_to_pin'` or
+`'ignore_pin'` to resolve baseline-pin conflicts.
+
+### Annotations — `client.annotations`
+
+| Method | Returns | Description |
+|---|---|---|
+| `list(eval_id)` | `list[Annotation]` | List for an evaluation |
+| `create(eval_id, content, **kwargs)` | `Annotation` | Create SLO-level annotation |
+| `create_for_run(run_id, content, **kwargs)` | `Annotation` | Create run-level annotation |
+| `update(eval_id, ann_id, **kwargs)` | `Annotation` | Update an annotation |
+| `hide(eval_id, ann_id, reason, author=None)` | `Annotation` | Soft-delete |
+
+### Trend — `client.trend`
+
+| Method | Returns | Description |
+|---|---|---|
+| `by_eval(eval_id, metric, from_, *, to=)` | `list[TrendPoint]` | Trend by evaluation ID |
+| `by_asset(asset_name, slo_name, metric, from_, *, to=)` | `list[TrendPoint]` | Trend by asset + SLO |
+
+## Manifest System
+
+The manifest system enables declarative, infrastructure-as-code management of TROPEK
+resources using YAML files.
+
+### Manifest Format
+
+Each manifest document has four fields:
+
+```yaml
+api_version: tropek/v1
+kind: Asset
+metadata:
+  name: web-api
+  display_name: Web API
+  tags:
+    env: prod
+spec:
+  type_name: service
+```
+
+Supported kinds (processed in dependency order):
+`AssetType`, `DataSource`, `Asset`, `SLI`, `SLO`, `AssetGroup`, `SLOGroup`,
+`SLOAssignment`, `SLOGroupAssignment`.
+
+A single file can contain multiple documents separated by `---`. You can also point
+at a directory — all `*.yaml` and `*.yml` files are loaded.
+
+### SLO Assignment Manifest
+
+```yaml
+api_version: tropek/v1
+kind: SLOAssignment
+metadata:
+  name: web-api-latency-assignment
+spec:
+  target_type: asset        # or asset_group
+  target_name: web-api
+  slo_name: latency-slo
+  data_source_name: prometheus
+```
+
+### Reconciliation
+
+The manifest system uses desired-state reconciliation:
+1. Load and parse all YAML documents
+2. Topologically sort by kind dependency
+3. For each document, look up the existing resource via the API
+4. Compare fields to detect drift (CREATE / UPDATE / SKIP)
+5. Apply changes, blocking dependent kinds on failure
+
+### Programmatic Usage
+
+```python
+from tropek_client import TropekClient
+from tropek_client.manifest import load_manifests, apply, dry_run
+
+docs = load_manifests('manifests/')
+
+with TropekClient('http://localhost:8080') as client:
+    # Preview changes
+    plan = dry_run(client, docs)
+    for action in plan.actions:
+        print(f'{action.operation}  {action.kind}/{action.name}')
+
+    # Apply
+    result = apply(client, docs)
+    print(f'{result.created} created, {result.updated} updated')
+```
+
+## CLI Usage
+
+The CLI is installed as `tropek` (entry point defined in pyproject.toml).
+
+### Validate manifests
+
+```bash
+tropek validate -f manifests/
+tropek validate -f my-slo.yaml
+```
+
+Checks syntax and cross-references without contacting the API.
+
+### Apply manifests
+
+```bash
+# Dry run — show what would change
+tropek apply --dry-run -f manifests/ --base-url http://localhost:8080
+
+# Apply changes
+tropek apply -f manifests/ --base-url http://localhost:8080 --api-key my-key
+```
+
+### Export current state
+
+```bash
+# To stdout
+tropek export --base-url http://localhost:8080
+
+# To file
+tropek export -f backup.yaml --base-url http://localhost:8080 --api-key my-key
+```
+
+Exports all resources (asset types, datasources, assets, SLIs, SLOs, groups,
+assignments) as a multi-document YAML manifest.
+
+## Known Limitations
+
+- **Asset names are globally unique.** There is no per-group scoping — two groups
+  cannot each contain an asset named `load_test`. Assets are identified by name
+  across the entire TROPEK instance.
+
+- **Display groups (`client.display_groups`) are half-baked.** The API exposes
+  `/slo-display-groups` as a standalone CRUD resource for organizing generated SLOs
+  into named visual buckets, but the feature is incomplete: no FK linking display
+  groups to the SLO group they belong to, no validation that member SLO names
+  exist, and no UI consumer. The client wraps the routes but they are untested
+  against real workflows. This will likely be redesigned when SLO group navigation
+  is revisited.
+
+## Error Handling
+
+All API errors raise typed exceptions:
+
+| Exception | HTTP Status | When |
+|---|---|---|
+| `TropekNotFoundError` | 404 | Resource not found |
+| `TropekConflictError` | 409 | Resource conflict (duplicate name) |
+| `TropekValidationError` | 422 | Request validation failed |
+| `TropekAPIError` | any non-2xx | Base class for all errors |
+
+Each exception has `status_code` and `detail` attributes:
+
+```python
+from tropek_client import TropekClient, TropekNotFoundError
+
+with TropekClient('http://localhost:8080') as client:
+    try:
+        client.assets.get('nonexistent')
+    except TropekNotFoundError as e:
+        print(e.status_code)  # 404
+        print(e.detail)       # "asset 'nonexistent' not found"
+```

tropek_client-0.1.1a0/docs/architecture.md

@@ -0,0 +1,137 @@
+# Python Client — Architecture
+
+Contributor guide for `clients/python/tropek_client/`.
+
+## Module Structure
+
+```
+tropek_client/
+├── __init__.py       # Public API: TropekClient + exception classes
+├── client.py         # HTTP client with resource-namespaced methods
+├── models.py         # Pydantic response models
+├── manifest.py       # YAML manifest loader and reconciler
+├── cli.py            # Click CLI interface
+└── exceptions.py     # Typed exception hierarchy
+```
+
+## Client Design (`client.py`)
+
+The client uses **namespace classes** to group API methods by resource type. Each
+namespace (e.g., `_Assets`, `_SLODefinitions`) is a private class that receives a
+shared `httpx.Client` instance. `TropekClient.__init__` instantiates all namespaces
+and exposes them as public attributes.
+
+HTTP pattern for every method:
+1. Build params/body dict, omitting `None` values
+2. Call `self._http.{verb}(path, ...)` 
+3. Pass response through `_raise_for_status()` (maps status codes to typed exceptions)
+4. Deserialize via `Model.model_validate(resp.json())`
+
+Paginated endpoints return `PagedResponse[T]` (items + total). Non-paginated
+endpoints return the model directly or a raw `dict` for polymorphic responses
+(evaluations trigger, batch, re-evaluate).
+
+`TropekClient` implements the context manager protocol for automatic cleanup.
+
+## Error Handling (`exceptions.py`)
+
+Four-class hierarchy:
+- `TropekAPIError(status_code, detail)` — base, catches any non-2xx
+- `TropekNotFoundError(detail)` — 404
+- `TropekConflictError(detail)` — 409
+- `TropekValidationError(detail)` — 422
+
+`_raise_for_status()` uses structural pattern matching on `resp.status_code`.
+The response body's `detail` field is extracted when available; raw text is the fallback.
+
+## Models (`models.py`)
+
+Pydantic v2 models mirroring API response schemas. Key patterns:
+- `PagedResponse[T]` — generic paginated wrapper using Python 3.12+ type parameter syntax
+- `ConfigDict(from_attributes=True)` on ORM-mapped models for compatibility
+- `EvaluationDetail` extends `EvaluationSummary` (adds annotations, indicator results)
+- Request models (`SLOTestRequest`, `BaselineConfig`) for structured input
+- String IDs on assignment models (`SLOAssignment`, `SLOGroupAssignment`) — the API
+  returns UUIDs as strings in some endpoints
+
+## Manifest System (`manifest.py`)
+
+### Processing Pipeline
+
+```
+load_manifests(path)
+    ├── _load_file()          # YAML multi-doc parsing
+    ├── _parse_document()     # Validate required fields, known kinds
+    └── _topological_sort()   # Sort by _KIND_ORDER dependency
+
+validate_manifests(path)
+    ├── load_manifests()
+    └── _validate_doc_refs()  # Cross-reference warnings
+
+dry_run(client, manifests)
+    └── for each doc:
+        ├── _lookup()         # Fetch existing resource from API
+        ├── _has_diff()       # Field-level comparison
+        └── → PlanAction(CREATE | UPDATE | SKIP)
+
+apply(client, manifests)
+    ├── dry_run()             # Build plan first
+    └── for each action:
+        ├── _create()         # Kind-specific create dispatch
+        ├── _update()         # Kind-specific update dispatch
+        └── _dependents_of()  # Block downstream kinds on failure
+```
+
+### Dependency Graph
+
+`_KIND_ORDER` defines processing order: `AssetType → DataSource → Asset → SLI → SLO
+→ AssetGroup → SLOGroup → SLOAssignment → SLOGroupAssignment`.
+
+`_KIND_DEPS` maps each kind to its dependents for error propagation — if an `Asset`
+creation fails, `AssetGroup`, `SLOAssignment`, and `SLOGroupAssignment` are blocked.
+
+### Update Semantics
+
+- **Versioned resources** (SLI, SLO): updates create a new version via the same
+  `create` endpoint rather than patching in place.
+- **Immutable resources** (SLOAssignment, SLOGroupAssignment): `_has_diff` always
+  returns `False` — requires manual delete + recreate.
+- **AssetGroup**: member/subgroup sync not yet implemented; updates are skipped.
+
+## CLI (`cli.py`)
+
+Click command tree with three commands:
+
+- `tropek validate -f <path>` — offline YAML validation
+- `tropek apply -f <path> [--dry-run] [--base-url] [--api-key]` — reconcile manifests
+- `tropek export [-f <path>] [--base-url] [--api-key]` — dump current state as YAML
+
+`export` uses `_collect_documents()` which iterates all resource types and builds
+manifest dicts. It also walks per-asset and per-group SLO assignments.
+
+## Test Structure
+
+```
+tests/
+├── test_client.py     # HTTP mocking via pytest-httpx; covers CRUD + error mapping
+├── test_manifest.py   # Manifest loading, sorting, dry_run, apply with MagicMock client
+├── test_cli.py        # Click CliRunner tests for validate + apply --dry-run
+└── test_models.py     # Pydantic model_validate round-trips
+```
+
+Dev dependencies: `pytest`, `pytest-httpx` (for `HTTPXMock` fixture).
+
+Tests use `MagicMock` for the client in manifest/CLI tests and `HTTPXMock` for
+HTTP-level client tests. No real API calls in any test.
+
+## Known Limitations
+
+See [`technical-debt.md`](technical-debt.md) for detailed analysis and recommended
+fixes. Summary:
+
+- No contract validation against the backend OpenAPI spec — client can silently drift
+- `AssetGroup` update via manifests is a no-op (member sync not implemented)
+- Assignment updates require manual delete + recreate
+- No async client variant
+- `export` does not include SLO group assignments
+- Some endpoints return raw `dict` instead of typed models (evaluation triggers)