uptimely-core 0.1.0.dev0__tar.gz → 0.2.0.dev0__tar.gz

{uptimely_core-0.1.0.dev0 → uptimely_core-0.2.0.dev0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: uptimely-core
-Version: 0.1.0.dev0
-Summary: Declarative numerical analytics with complex dependencies at scale
+Version: 0.2.0.dev0
+Summary: Manage data-driven numerical analytics with complex dependencies at scale
 License-Expression: MIT
 License-File: LICENSE
 Keywords: analytics,declarative,industrial,feature-engineering,polars
@@ -24,15 +24,18 @@ Requires-Dist: numpy (>=1.26,<3.0)
 Requires-Dist: polars (>=1.0,<2.0)
 Requires-Dist: pydantic (>=2.10,<3.0)
 Project-URL: Documentation, https://uptimely-ai.github.io/uptimely-core
-Project-URL: Homepage, https://github.com/uptimely-ai/uptimely-core
+Project-URL: Homepage, http://uptimely.ai/core/
 Project-URL: Repository, https://github.com/uptimely-ai/uptimely-core
 Description-Content-Type: text/markdown
 
 # Uptimely Core
 
-Uptimely Core is an open source Python package for declarative numerical analytics with complex dependencies at scale.
+Uptimely Core is an open source Python package for declarative numerical
+analytics with complex dependencies at scale.
 
-It describes analytics workflows in a specification similar to OpenAPI, uses a declarative model inspired by Kubernetes. The framework generates plans, graphs, and documentation from that specification.
+Analytics definitions describe workflows in JSON, using a declarative model
+inspired by OpenAPI and Kubernetes. The compiler generates plans from the
+analytics; the package can also render dependency graphs and documentation.
 
 Ships with simple engine and plans to integrate to common execution backends.
 
@@ -53,15 +56,26 @@ Read more at [uptimely.ai website](https://uptimely.ai).
 
 ## Quick start
 
-Install the package, download examples and run.
+Python 3.13 or newer is required. Install the package, download the examples
+and run.
+
+With pip:
 
 ```sh
 pip install uptimely-core
 uptimely examples download
-python examples/run_all.py
+uptimely explorer serve --project-root examples/pump_analytics
+```
+
+With Poetry, from your Poetry project:
+
+```sh
+poetry add uptimely-core
+poetry run uptimely examples download
+poetry run uptimely explorer serve --project-root examples/pump_analytics
 ```
 
-Explore the examples files, generated resources and modify for the needs of your own project.
+More use cases in [examples](examples/README.md). Explore the examples files, generated resources and modify for the needs of your own project.
 
 ## Documentation
 
@@ -74,7 +88,7 @@ Explore the [documentation site](https://uptimely-ai.github.io/uptimely-core/).
 | [`docs/`](docs/index.md) | Architecture, specification, and development documentation. |
 | [`examples/`](examples/README.md) | Runnable examples and generated artifacts. |
 | [`scripts/`](scripts) | Code snippets for repository management |
-| [`src/uptimely/`](src/uptimely/) | Package implementation for specifications, compilation, dependencies, documentation, and engine. |
+| [`src/uptimely/`](src/uptimely/) | Package implementation for analytics, compilation, dependencies, documentation, and execution. |
 | [`tests/`](tests/) | Automated tests for the package and examples. |
 
 ## Development

{uptimely_core-0.1.0.dev0 → uptimely_core-0.2.0.dev0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "uptimely-core"
-version = "0.1.0.dev0"
-description = "Declarative numerical analytics with complex dependencies at scale"
+version = "0.2.0.dev0"
+description = "Manage data-driven numerical analytics with complex dependencies at scale"
 authors = [{ name = "Mikael Ahonen", email = "mikael.ahonen@uptimely.ai" }]
 license = "MIT"
 license-files = ["LICENSE"]
@@ -39,12 +39,12 @@ uptimely = "uptimely.cli.cli:main"
 uptimely-mcp = "uptimely.mcp.server:main"
 
 [project.urls]
-Homepage = "https://github.com/uptimely-ai/uptimely-core"
+Homepage = "http://uptimely.ai/core/"
 Repository = "https://github.com/uptimely-ai/uptimely-core"
 Documentation = "https://uptimely-ai.github.io/uptimely-core"
 
 [dependency-groups]
-test = ["pytest>=8.0", "pytest-cov>=5.0"]
+test = ["pytest>=8.0", "pytest-cov>=5.0", "pytest-xdist (>=3.6,<4.0)"]
 dev = ["pre-commit>=3.0", "ruff>=0.8"]
 docs = ["mkdocs>=1.6,<2.0", "mkdocs-material>=9.7,<10.0", "mkdocstrings[python]>=1.0,<2.0"]
 
@@ -68,7 +68,7 @@ convention = "google"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "--strict-markers --strict-config"
+addopts = "--strict-markers --strict-config -n 4"
 markers = [
   "integration: end-to-end tests using example projects",
 ]

{uptimely_core-0.1.0.dev0 → uptimely_core-0.2.0.dev0}/readme.md

@@ -1,8 +1,11 @@
 # Uptimely Core
 
-Uptimely Core is an open source Python package for declarative numerical analytics with complex dependencies at scale.
+Uptimely Core is an open source Python package for declarative numerical
+analytics with complex dependencies at scale.
 
-It describes analytics workflows in a specification similar to OpenAPI, uses a declarative model inspired by Kubernetes. The framework generates plans, graphs, and documentation from that specification.
+Analytics definitions describe workflows in JSON, using a declarative model
+inspired by OpenAPI and Kubernetes. The compiler generates plans from the
+analytics; the package can also render dependency graphs and documentation.
 
 Ships with simple engine and plans to integrate to common execution backends.
 
@@ -23,15 +26,26 @@ Read more at [uptimely.ai website](https://uptimely.ai).
 
 ## Quick start
 
-Install the package, download examples and run.
+Python 3.13 or newer is required. Install the package, download the examples
+and run.
+
+With pip:
 
 ```sh
 pip install uptimely-core
 uptimely examples download
-python examples/run_all.py
+uptimely explorer serve --project-root examples/pump_analytics
+```
+
+With Poetry, from your Poetry project:
+
+```sh
+poetry add uptimely-core
+poetry run uptimely examples download
+poetry run uptimely explorer serve --project-root examples/pump_analytics
 ```
 
-Explore the examples files, generated resources and modify for the needs of your own project.
+More use cases in [examples](examples/README.md). Explore the examples files, generated resources and modify for the needs of your own project.
 
 ## Documentation
 
@@ -44,7 +58,7 @@ Explore the [documentation site](https://uptimely-ai.github.io/uptimely-core/).
 | [`docs/`](docs/index.md) | Architecture, specification, and development documentation. |
 | [`examples/`](examples/README.md) | Runnable examples and generated artifacts. |
 | [`scripts/`](scripts) | Code snippets for repository management |
-| [`src/uptimely/`](src/uptimely/) | Package implementation for specifications, compilation, dependencies, documentation, and engine. |
+| [`src/uptimely/`](src/uptimely/) | Package implementation for analytics, compilation, dependencies, documentation, and execution. |
 | [`tests/`](tests/) | Automated tests for the package and examples. |
 
 ## Development

uptimely_core-0.2.0.dev0/src/uptimely/__init__.py

@@ -0,0 +1,40 @@
+"""Public package namespace for uptimely."""
+
+from .analytics import (
+    Analytics,
+    Call,
+    Dimension,
+    Entity,
+    FeatureGraph,
+    Function,
+    PreparedAnalytics,
+    PythonAnalytics,
+    SubGraph,
+    from_python,
+    load_analytics,
+    prepare_analytics,
+    write_document,
+)
+from .compiler import CallableGraph, CallableNode, Compiler, ExecutionPlan
+from .engine import Engine
+
+__all__ = [
+    "Analytics",
+    "Call",
+    "CallableGraph",
+    "CallableNode",
+    "Compiler",
+    "Dimension",
+    "Entity",
+    "ExecutionPlan",
+    "Function",
+    "PythonAnalytics",
+    "PreparedAnalytics",
+    "from_python",
+    "load_analytics",
+    "prepare_analytics",
+    "write_document",
+    "SubGraph",
+    "FeatureGraph",
+    "Engine",
+]

uptimely_core-0.2.0.dev0/src/uptimely/analytics/__init__.py

@@ -0,0 +1,65 @@
+"""Public package namespace for OpenAnalytics analytics."""
+
+from uptimely.row_context import RowContext
+
+from .api import from_python, load_analytics, prepare_analytics
+from .feature_graph import FeatureGraph, SubGraph
+from .json.codec import write_document
+from .model import (
+    Analytics,
+    Argument,
+    Binding,
+    Dataset,
+    Dimension,
+    Entity,
+    Feature,
+    FunctionCatalog,
+    Mapping,
+    Order,
+    RowScope,
+)
+from .python import (
+    PythonAnalytics,
+    bind,
+    dataset,
+    dimension,
+    entity,
+    feature,
+    mapping,
+    ref,
+    row_context,
+)
+from .resolved import Call, Function, PreparedAnalytics
+
+__all__ = [
+    "Argument",
+    "Binding",
+    "Call",
+    "Dataset",
+    "Dimension",
+    "Entity",
+    "Feature",
+    "FeatureGraph",
+    "Function",
+    "FunctionCatalog",
+    "Mapping",
+    "Order",
+    "PythonAnalytics",
+    "RowContext",
+    "RowScope",
+    "Analytics",
+    "PreparedAnalytics",
+    "from_python",
+    "load_analytics",
+    "prepare_analytics",
+    "write_document",
+    "SubGraph",
+    "bind",
+    "dataset",
+    "dimension",
+    "entity",
+    "feature",
+    "mapping",
+    "ref",
+    "row_context",
+]

uptimely_core-0.2.0.dev0/src/uptimely/analytics/api.py

@@ -0,0 +1,82 @@
+"""Build and load validated analytics through explicit application operations."""
+
+from __future__ import annotations
+
+import pathlib
+
+from . import model, resolution, resolved, validation
+from .json import codec
+from .python import conversion
+
+
+def prepare_analytics(document: model.Analytics) -> resolved.PreparedAnalytics:
+    """Resolve and validate a document without adding derived state to it.
+
+    Preparation uses declarative metadata, not executable Python signatures.
+    Rebuild the result after changing the document; it is not an automatic cache.
+
+    Args:
+        document: An analytics document that conforms to the document model.
+
+    Returns:
+        The document paired with its resolved functions and calls.
+
+    Raises:
+        ValueError: Analytics references, mappings, or dependencies are invalid.
+    """
+    functions, calls = resolution.resolve_functions(document)
+    validation.validate_prepared(document, functions, calls)
+    return resolved.PreparedAnalytics(document=document, functions=functions, calls=calls)
+
+
+def load_analytics(path: str | pathlib.Path) -> model.Analytics:
+    """Load and semantically validate an analytics JSON file or directory.
+
+    Args:
+        path: A JSON document or a directory containing ``analytics.json``.
+
+    Returns:
+        A validated analytics document without attached derived state.
+
+    Raises:
+        OSError: The JSON document cannot be read.
+        ValueError: The document or its analytics declarations are invalid.
+    """
+    document = model.Analytics.model_validate(codec.load_document(path))
+    prepare_analytics(document)
+    return document
+
+
+def from_python(
+    datasets: conversion.Datasets | None = None,
+    functions: conversion.Functions | None = None,
+    name: str | None = None,
+    dimensions: conversion.Dimensions | None = None,
+    *,
+    entities: conversion.Entities | None = None,
+) -> model.Analytics:
+    """Convert Python declarations and semantically validate the resulting model.
+
+    Args:
+        datasets: Dataset declarations wrapped in a single entity.
+        functions: Explicit catalog, or infer it from Python declarations.
+        name: Optional analytics name and synthetic entity identifier.
+        dimensions: Global dimension declarations.
+        entities: Explicit entity declarations, mutually exclusive with datasets.
+
+    Returns:
+        A validated analytics document without attached derived state.
+
+    Raises:
+        TypeError: Declarations have unsupported types.
+        ValueError: Declarations conflict or analytics semantics are invalid.
+    """
+    document = conversion.to_model(
+        datasets=datasets,
+        functions=functions,
+        name=name,
+        dimensions=dimensions,
+        entities=entities,
+    )
+    prepare_analytics(document)
+    return document

uptimely_core-0.2.0.dev0/src/uptimely/analytics/catalog.py

@@ -0,0 +1,41 @@
+"""Shared function-catalog construction, merging, and serialization."""
+
+from __future__ import annotations
+
+import collections.abc
+
+from uptimely import contracts
+
+from . import model as analytics_model
+
+
+def function_template(
+    function_id: str,
+    operation: contracts.FunctionOperation,
+    entrypoint: str,
+    args: dict[str, analytics_model.Argument],
+) -> analytics_model.FunctionTemplate:
+    """Create a function template for the analytics document from its declarations."""
+    return analytics_model.FunctionTemplate(
+        id=function_id,
+        operation=operation,
+        returns=contracts.OPERATION_RETURN_KINDS[operation],
+        entrypoint=entrypoint,
+        args=args,
+    )
+
+
+def merge_function_catalogs(
+    catalogs: collections.abc.Iterable[analytics_model.FunctionCatalog],
+) -> dict[str, analytics_model.FunctionTemplate]:
+    """Merge identical definitions and reject conflicting templates."""
+    functions: dict[str, analytics_model.FunctionTemplate] = {}
+    for catalog in catalogs:
+        for function_id, function in catalog.root.items():
+            current = functions.get(function_id)
+            if current is None:
+                functions[function_id] = function
+                continue
+            if current != function:
+                raise ValueError(f"Conflicting function definition for '{function_id}'")
+    return functions

uptimely_core-0.2.0.dev0/src/uptimely/analytics/feature_graph/__init__.py

@@ -0,0 +1,14 @@
+"""Feature dependency graph models and visualization."""
+
+from .graph import FeatureGraph, GraphBase, Node, NodeMeta, SubGraph
+from .models import FeatureNode, FunctionNode
+
+__all__ = [
+    "FeatureGraph",
+    "FeatureNode",
+    "FunctionNode",
+    "GraphBase",
+    "Node",
+    "NodeMeta",
+    "SubGraph",
+]