[PD1-296] Initial version: SDK for spans and metrics

.aider.conf.yml

@@ -0,0 +1,7 @@
+lint-cmd: 
+  - "python: scripts/lint.sh"
+auto-lint: true
+test-cmd: poetry run pytest
+auto-test: true
+read:
+  - README.md

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: Python CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+      with:
+        virtualenvs-create: true
+        virtualenvs-in-project: true
+        installer-parallel: true
+
+    - name: Load cached venv
+      id: cached-poetry-dependencies
+      uses: actions/cache@v4
+      with:
+        path: .venv
+        key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+
+    - name: Install dependencies
+      if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+      run: poetry install --no-interaction --no-root
+
+    - name: Install project
+      run: poetry install --no-interaction
+
+    - name: Ruff lint check
+      run: |
+        poetry run ruff check .
+
+    - name: Ruff format check
+      run: |
+        poetry run ruff format --check .
+
+    - name: Type check
+      run: |
+        poetry run mypy --strict .
+
+    - name: Run tests
+      run: |
+        poetry run pytest

.gitignore

@@ -172,3 +172,4 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+.aider*

README.md

@@ -1,2 +1,148 @@
-# cvec-python
-CVector SDK for Python
+# CVec Client Library
+
+The "cvec" package is the Python SDK for CVector Energy.
+
+# Getting Started
+
+## Installation
+
+Assuming that you have a supported version of Python installed, you can first create a venv with:
+
+```
+python -m venv .venv
+```
+
+Then, activate the venv:
+
+```
+. .venv/bin/activate
+```
+
+Then, you can install cvec from PyPI with:
+
+```
+pip install cvec
+```
+
+## Using cvec
+
+Import the cvec package. We will also use the datetime module.
+
+```
+import cvec
+from datetime import datetime
+```
+
+Construct the CVec client. The host, tenant, and api_key can be given through parameters to the constructor or from the environment variables CVEC_HOST, CVEC_TENANT, and CVEC_API_KEY:
+
+```
+cvec = cvec.CVec()
+```
+
+### Spans
+
+A span is a period of interest, such as an experiment, a baseline recording session, or an alarm. The initial state of a Span is implicitly defined by a period where a given metric has a constant value.
+
+The newest span for a metric does not have an end time, since it has not ended yet (or has not ended by the finish of the queried period).
+
+To get the spans on `my_tag_name` since 2025-05-14 10am, run:
+
+```
+for span in cvec.get_spans("mygroup/myedge/mode", start_at=datetime(2025, 5, 14, 10, 0, 0)):
+    print("%s\t%s" % (span.value, span.raw_start_at))
+```
+
+The output will be like:
+
+```
+offline   2025-05-19 16:28:02.130000+00:00
+starting  2025-05-19 16:28:01.107000+00:00
+running   2025-05-19 15:29:28.795000+00:00
+stopping  2025-05-19 15:29:27.788000+00:00
+offline   2025-05-19 14:14:43.752000+00:00
+```
+
+### Metrics
+
+A metric is a named set of time-series data points pertaining to a particular resource (for example, the value reported by a sensor). Metrics can have numeric or string values. Boolean values are mapped to 0 and 1. The get_metrics function returns a list of metric metadata.
+
+To get all of the metrics that changed value at 10am on 2025-05-14, run:
+
+```
+for item in cvec.get_metrics(start_at=datetime(2025, 5, 14, 10, 0, 0), end_at=datetime(2025, 5, 14, 11, 0, 0)):
+  print(item.name)
+```
+
+Example output:
+
+```
+mygroup/myedge/compressor01/status
+mygroup/myedge/compressor01/interlocks/emergency_stop
+mygroup/myedge/compressor01/stage1/pressure_out/psig
+mygroup/myedge/compressor01/stage1/temp_out/c
+mygroup/myedge/compressor01/stage2/pressure_out/psig
+mygroup/myedge/compressor01/stage2/temp_out/c
+mygroup/myedge/compressor01/motor/current/a
+mygroup/myedge/compressor01/motor/power_kw
+```
+
+### Metric Data
+
+The main content for a metric is a set of points where the metric value changed. These are returned as a Pandas Dataframe with columns for name, time, value_double, value_string.
+
+To get all of the value changes for all metrics at 10am on 2025-05-14, run:
+
+```
+cvec.get_metric_data(start_at=datetime(2025, 5, 14, 10, 0, 0), end_at=datetime(2025, 5, 14, 11, 0, 0))
+```
+
+Example output:
+
+```
+                                                        name                             time  value_double value_string
+0      mygroup/myedge/mode                                   2025-05-14 10:10:41.949000+00:00     24.900000     starting
+1      mygroup/myedge/compressor01/interlocks/emergency_stop 2025-05-14 10:27:24.899000+00:00     0.0000000         None
+2      mygroup/myedge/compressor01/stage1/pressure_out/psig  2025-05-14 10:43:38.282000+00:00     123.50000         None
+3      mygroup/myedge/compressor01/stage1/temp_out/c         2025-05-14 10:10:41.948000+00:00     24.900000         None
+4      mygroup/myedge/compressor01/motor/current/a           2025-05-14 10:27:24.897000+00:00     12.000000         None
+...                                   ...                              ...           ...          ...
+46253  mygroup/myedge/compressor01/stage1/temp_out/c         2025-05-14 10:59:55.725000+00:00     25.300000         None
+46254  mygroup/myedge/compressor01/stage2/pressure_out/psig  2025-05-14 10:59:56.736000+00:00     250.00000         None
+46255  mygroup/myedge/compressor01/stage2/temp_out/c         2025-05-14 10:59:57.746000+00:00     12.700000         None
+46256  mygroup/myedge/compressor01/motor/current/a           2025-05-14 10:59:58.752000+00:00     11.300000         None
+46257  mygroup/myedge/compressor01/motor/power_kw            2025-05-14 10:59:59.760000+00:00     523.40000         None
+
+[46257 rows x 4 columns]
+```
+
+# CVec Class
+
+The SDK provides an API client class named `CVec` with the following functions.
+
+## `__init__(?host, ?tenant, ?api_key, ?default_start_at, ?default_end_at)`
+
+Setup the SDK with the given host and API Key. The host and API key are loaded from environment variables CVEC_HOST, CVEC_TENANT, CVEC_API_KEY, if they are not given as arguments to the constructor. The `default_start_at` and `default_end_at` can provide a default query time interval for API methods.
+
+## `get_spans(name, ?start_at, ?end_at, ?limit)`
+
+Return time spans for a metric. Spans are generated from value changes that occur after `start_at` (if specified) and before `end_at` (if specified).
+If `start_at` is `None` (e.g., not provided as an argument and no class default `default_start_at` is set), the query for value changes is unbounded at the start. Similarly, if `end_at` is `None`, the query is unbounded at the end.
+
+Each `Span` object in the returned list represents a period where the metric's value is constant and has the following attributes:
+- `value`: The metric's value during the span.
+- `name`: The name of the metric.
+- `raw_start_at`: The timestamp of the value change that initiated this span's value. This will be greater than or equal to the query's `start_at` if one was specified.
+- `raw_end_at`: The timestamp marking the end of this span's constant value. For the newest span, the value is `None`. For other spans, it's the raw_start_at of the immediately newer data point, which is next span in the list.
+- `id`: Currently `None`. In a future version of the SDK, this will be the span's unique identifier.
+- `metadata`: Currently `None`. In a future version, this can be used to store annotations or other metadata related to the span.
+
+Returns a list of `Span` objects, sorted in descending chronological order (newest span first).
+If no relevant value changes are found, an empty list is returned.
+
+## `get_metric_data(?names, ?start_at, ?end_at)`
+
+Return all data-points within a given [`start_at`, `end_at`) interval, optionally selecting a given list of metric names. The return value is a Pandas DataFrame with four columns: name, time, value_double, value_string. One row is returned for each metric value transition.
+
+## `get_metrics(?start_at, ?end_at)`
+
+Return a list of metrics that had at least one transition in the given [`start_at`, `end_at`) interval. All metrics are returned if no `start_at` and `end_at` are given.