cvec 0.1.0__tar.gz

cvec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CVector Energy
+
+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, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

cvec-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.3
+Name: cvec
+Version: 0.1.0
+Summary: SDK for CVector Energy
+Author: CVector
+Author-email: support@cvector.energy
+Requires-Python: >=3.10
+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
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: psycopg (>=3.1.0,<4.0.0)
+Description-Content-Type: text/markdown
+
+# 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.
+

cvec-0.1.0/README.md

@@ -0,0 +1,148 @@
+# 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.

cvec-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "cvec"
+version = "0.1.0"
+description = "SDK for CVector Energy"
+authors = [
+    {name = "CVector",email = "support@cvector.energy"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pandas (>=2.2.3,<3.0.0)",
+    "psycopg (>=3.1.0,<4.0.0)"  # Assuming a recent version of psycopg3
+]
+
+[tool.poetry]
+packages = [{include = "cvec", from = "src"}]
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+mypy = "^1.15.0"
+pandas-stubs = "^2.2.3.250308"
+ruff = "^0.11.10"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

cvec-0.1.0/src/cvec/__init__.py

@@ -0,0 +1,5 @@
+from .cvec import CVec
+from .span import Span
+from .metric import Metric
+
+__all__ = ["CVec", "Span", "Metric"]

cvec-0.1.0/src/cvec/cvec.py

@@ -0,0 +1,242 @@
+import os
+from datetime import datetime
+from typing import Any, List, Optional
+
+import pandas as pd
+import psycopg
+
+from .span import Span
+from .metric import Metric
+
+
+class CVec:
+    """
+    CVec API Client
+    """
+
+    host: Optional[str]
+    tenant: Optional[str]
+    api_key: Optional[str]
+    default_start_at: Optional[datetime]
+    default_end_at: Optional[datetime]
+
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        tenant: Optional[str] = None,
+        api_key: Optional[str] = None,
+        default_start_at: Optional[datetime] = None,
+        default_end_at: Optional[datetime] = None,
+    ) -> None:
+        """
+        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.
+        """
+        self.host = host or os.environ.get("CVEC_HOST")
+        self.tenant = tenant or os.environ.get("CVEC_TENANT")
+        self.api_key = api_key or os.environ.get("CVEC_API_KEY")
+        self.default_start_at = default_start_at
+        self.default_end_at = default_end_at
+
+        if not self.host:
+            raise ValueError(
+                "CVEC_HOST must be set either as an argument or environment variable"
+            )
+        if not self.tenant:
+            raise ValueError(
+                "CVEC_TENANT must be set either as an argument or environment variable"
+            )
+        if not self.api_key:
+            raise ValueError(
+                "CVEC_API_KEY must be set either as an argument or environment variable"
+            )
+
+    def _get_db_connection(self) -> psycopg.Connection:
+        """Helper method to establish a database connection."""
+        return psycopg.connect(
+            user=self.tenant,
+            password=self.api_key,
+            host=self.host,
+            dbname=self.tenant,
+        )
+
+    def get_spans(
+        self,
+        name: str,
+        start_at: Optional[datetime] = None,
+        end_at: Optional[datetime] = None,
+        limit: Optional[int] = None,
+    ) -> List[Span]:
+        """
+        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 via argument or class default),
+        the query is unbounded at the start. If `end_at` is `None`, it's unbounded at the end.
+
+        Each span represents a period where the metric's value is constant.
+        - `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 >= `_start_at` if `_start_at` 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`.
+        - `metadata`: Currently `None`.
+
+        Returns a list of Span objects, sorted in descending chronological order (newest span first).
+        Each Span object has attributes corresponding to the fields listed above.
+        If no relevant value changes are found, an empty list is returned.
+        The `limit` parameter restricts the number of spans returned.
+        """
+        _start_at = start_at or self.default_start_at
+        _end_at = end_at or self.default_end_at
+
+        with self._get_db_connection() as conn:
+            with conn.cursor() as cur:
+                query_params = {
+                    "metric": name,
+                    "start_at": _start_at,
+                    "end_at": _end_at,
+                    # Fetch up to 'limit' points. If limit is None, then the `LIMIT NULL` clause
+                    # has no effect (in PostgreSQL).
+                    "limit": limit,
+                }
+
+                combined_query = """
+                SELECT
+                    time,
+                    value_double,
+                    value_string
+                FROM metric_data
+                WHERE metric = %(metric)s
+                  AND (time >= %(start_at)s OR %(start_at)s IS NULL)
+                  AND (time < %(end_at)s OR %(end_at)s IS NULL)
+                ORDER BY time DESC
+                LIMIT %(limit)s
+                """
+                cur.execute(combined_query, query_params)
+                db_rows = cur.fetchall()
+                spans = []
+
+                # None indicates that the end time is not known; the span extends beyond
+                # the query period.
+                raw_end_at = None
+                for time, value_double, value_string in db_rows:
+                    raw_start_at = time
+                    value = value_double if value_double is not None else value_string
+                    spans.append(
+                        Span(
+                            id=None,
+                            name=name,
+                            value=value,
+                            raw_start_at=raw_start_at,
+                            raw_end_at=raw_end_at,
+                            metadata=None,
+                        )
+                    )
+                    raw_end_at = raw_start_at
+
+                return spans
+
+    def get_metric_data(
+        self,
+        names: Optional[List[str]] = None,
+        start_at: Optional[datetime] = None,
+        end_at: Optional[datetime] = None,
+    ) -> pd.DataFrame:
+        """
+        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.
+        """
+        _start_at = start_at or self.default_start_at
+        _end_at = end_at or self.default_end_at
+
+        params = {
+            "start_at": _start_at,
+            "end_at": _end_at,
+            "tag_names_is_null": names is None,
+            # Pass an empty tuple if names is None or empty, otherwise the tuple of names.
+            # ANY(%(empty_tuple)s) will correctly result in no matches if names is empty.
+            # If names is None, the tag_names_is_null condition handles it.
+            "tag_names_list": names if names else [],
+        }
+
+        sql_query = """
+            SELECT metric AS name, time, value_double, value_string
+            FROM metric_data
+            WHERE (time >= %(start_at)s OR %(start_at)s IS NULL)
+              AND (time < %(end_at)s OR %(end_at)s IS NULL)
+              AND (%(tag_names_is_null)s IS TRUE OR metric = ANY(%(tag_names_list)s))
+            ORDER BY name, time ASC
+        """
+
+        with self._get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql_query, params)
+                rows = cur.fetchall()
+
+        if not rows:
+            return pd.DataFrame(
+                columns=["name", "time", "value_double", "value_string"]
+            )
+
+        # Create DataFrame from fetched rows
+        df = pd.DataFrame(
+            rows, columns=["name", "time", "value_double", "value_string"]
+        )
+
+        # Return the DataFrame with the required columns
+        return df[["name", "time", "value_double", "value_string"]]
+
+    def get_metrics(
+        self, start_at: Optional[datetime] = None, end_at: Optional[datetime] = None
+    ) -> List[Metric]:
+        """
+        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.
+        """
+        sql_query: str
+        params: Optional[dict[str, Any]]
+
+        if start_at is None and end_at is None:
+            # No time interval specified by arguments, return all tags
+            sql_query = """
+                SELECT id, normalized_name AS name, birth_at, death_at
+                FROM tag_names
+                ORDER BY name ASC;
+            """
+            params = None
+        else:
+            # Time interval specified, find tags with transitions in the interval
+            _start_at = start_at or self.default_start_at
+            _end_at = end_at or self.default_end_at
+
+            params = {"start_at_param": _start_at, "end_at_param": _end_at}
+            sql_query = f"""
+                SELECT DISTINCT metric_id AS id, metric AS name, birth_at, death_at
+                FROM {self.tenant}.metric_data
+                WHERE (time >= %(start_at_param)s OR %(start_at_param)s IS NULL)
+                  AND (time < %(end_at_param)s OR %(end_at_param)s IS NULL)
+                ORDER BY name ASC;
+            """
+
+        with self._get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql_query, params)
+                rows = cur.fetchall()
+
+        # Format rows into list of Metric objects
+        metrics_list = [
+            Metric(
+                id=row[0],
+                name=row[1],
+                birth_at=row[2],
+                death_at=row[3],
+            )
+            for row in rows
+        ]
+        return metrics_list

cvec-0.1.0/src/cvec/metric.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+from typing import Optional
+
+
+class Metric:
+    """
+    Represents metadata for a metric.
+    """
+
+    id: int
+    name: str
+    birth_at: Optional[datetime]
+    death_at: Optional[datetime]
+
+    def __init__(
+        self,
+        id: int,
+        name: str,
+        birth_at: Optional[datetime],
+        death_at: Optional[datetime],
+    ):
+        self.id = id
+        self.name = name
+        self.birth_at = birth_at
+        self.death_at = death_at
+
+    def __repr__(self) -> str:
+        return (
+            f"Metric(id={self.id!r}, name={self.name!r}, "
+            f"birth_at={self.birth_at!r}, death_at={self.death_at!r})"
+        )

cvec-0.1.0/src/cvec/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

cvec-0.1.0/src/cvec/span.py

@@ -0,0 +1,42 @@
+from datetime import datetime
+from typing import Any, Optional, Union
+
+
+class Span:
+    """
+    Represents a time span where a metric has a constant value.
+    """
+
+    id: Optional[Any]
+    name: str
+    value: Optional[Union[float, str]]
+    raw_start_at: datetime
+    raw_end_at: Optional[datetime]
+    metadata: Optional[Any]
+
+    def __init__(
+        self,
+        id: Optional[Any],
+        name: str,
+        value: Optional[Union[float, str]],
+        raw_start_at: datetime,
+        raw_end_at: Optional[datetime],
+        metadata: Optional[Any],
+    ):
+        self.id = id
+        self.name = name
+        self.value = value
+        self.raw_start_at = raw_start_at
+        self.raw_end_at = raw_end_at
+        self.metadata = metadata
+
+    def __repr__(self) -> str:
+        raw_start_at_repr = (
+            self.raw_start_at.isoformat() if self.raw_start_at else "None"
+        )
+        raw_end_at_repr = self.raw_end_at.isoformat() if self.raw_end_at else "None"
+        return (
+            f"Span(id={self.id!r}, name={self.name!r}, value={self.value!r}, "
+            f"raw_start_at={raw_start_at_repr}, raw_end_at={raw_end_at_repr}, "
+            f"metadata={self.metadata!r})"
+        )