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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: uptimely-core
-Version: 0.1.0
-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.
 
@@ -56,15 +59,23 @@ Read more at [uptimely.ai website](https://uptimely.ai).
 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
 ```
 
-Read more from [examples](examples/README.md).
+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
 
@@ -77,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 → 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"
-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,7 +39,7 @@ 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"
 

{uptimely_core-0.1.0 → 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.
 
@@ -26,15 +29,23 @@ Read more at [uptimely.ai website](https://uptimely.ai).
 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
 ```
 
-Read more from [examples](examples/README.md).
+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
 
@@ -47,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",
+]

uptimely_core-0.1.0/src/uptimely/analytics/feature_graph.py → uptimely_core-0.2.0.dev0/src/uptimely/analytics/feature_graph/graph.py

@@ -5,9 +5,9 @@ import re
 import graphable as graphable_
 from graphable import views
 
-from uptimely import spec
-from uptimely.spec.json_spec import bindings
-
+from .. import api, resolved
+from .. import model as analytics_model
+from .. import references as bindings
 from . import models
 
 Node = graphable_.graphable.Graphable
@@ -19,7 +19,7 @@ class GraphBase:
 
     graph: graphable_.graph.Graph
     _node_index: dict[str, Node]
-    _function_catalog: dict[str, spec.Function]
+    _function_catalog: dict[str, resolved.Function]
     _explicit_output_names: list[str] | None
 
     @staticmethod
@@ -142,29 +142,30 @@ class GraphBase:
 class FeatureGraph(GraphBase):
     """Global dependency graph built from all feature mappings."""
 
-    def __init__(self, specs: spec.Specification) -> None:
+    def __init__(self, analytics: analytics_model.Analytics) -> None:
         """Load analytics function calls and build the complete dependency graph."""
+        prepared = api.prepare_analytics(analytics)
         self.functions = [
-            function for function in specs.resolved_functions if function.role == "analytics"
+            function for function in prepared.functions if function.role == "analytics"
         ]
-        self._graph_operations: list[tuple[spec.Function, str, str, list[str], list[str]]] = []
+        self._graph_operations: list[tuple[resolved.Function, str, str, list[str], list[str]]] = []
         vectorize_functions = {function.id: function for function in self.functions}
 
-        for entity_id, entity in specs.entities.items():
+        for entity_id, entity in analytics.entities.items():
             for dataset in entity.datasets:
                 for operation_id, mapping in dataset.mappings.items():
-                    operation_type = bindings.mapping_category(mapping, specs.functions)
-                    template = getattr(specs.functions, operation_type)[mapping.binding.function]
+                    operation = bindings.mapping_operation(mapping, analytics.functions)
+                    template = analytics.functions[mapping.binding.function]
                     function = (
                         vectorize_functions.get(mapping.binding.function)
-                        if operation_type == "vectorize"
-                        else spec.Function(
+                        if operation == "vectorize"
+                        else resolved.Function(
                             id=mapping.binding.function,
                             type="python_function",
                             return_type="dataframe",
                             info={"description": getattr(template, "description", None)},
                             entrypoint=template.entrypoint,
-                            role=operation_type,
+                            role=operation,
                         )
                     )
                     if function is None:
@@ -183,13 +184,13 @@ class FeatureGraph(GraphBase):
                             [
                                 feature_id
                                 for feature_id in mapping.output_features
-                                if feature_id not in specs.dimensions
+                                if feature_id not in analytics.dimensions
                             ],
                             list(dict.fromkeys(dependencies)),
                         )
                     )
 
-        self.specification = specs
+        self.analytics = analytics
         self._function_catalog = {function.id: function for function in self.functions}
         self._node_index: dict[str, Node] = {}
         self._explicit_output_names = None
@@ -199,7 +200,7 @@ class FeatureGraph(GraphBase):
         self,
         function_name: str,
         dependencies: list[str],
-        function: spec.Function | None = None,
+        function: resolved.Function | None = None,
     ) -> set[str]:
         """Return direct parent feature names for a bound feature."""
         function = function or self._function_catalog.get(function_name)
@@ -235,7 +236,7 @@ class FeatureGraph(GraphBase):
             output
             for _function, _entity, _operation_id, outputs, _dependencies in self._graph_operations
             for output in outputs
-            if output not in self.specification.dimensions
+            if output not in self.analytics.dimensions
         }
         dependency_names = {
             parent
@@ -263,20 +264,17 @@ class FeatureGraph(GraphBase):
                 ),
             )
 
-        for entity_id, entity in self.specification.entities.items():
+        for entity_id, entity in self.analytics.entities.items():
             for dataset in entity.datasets:
                 for mapping in dataset.mappings.values():
-                    operation_type = bindings.mapping_category(
-                        mapping, self.specification.functions
-                    )
+                    operation = bindings.mapping_operation(mapping, self.analytics.functions)
                     for name in mapping.output_features:
                         feature = dataset.features[name]
                         register_feature_metadata(
                             name,
                             feature.type,
                             entity_id,
-                            is_source_input=operation_type != "collapse"
-                            and operation_type != "vectorize",
+                            is_source_input=operation != "collapse" and operation != "vectorize",
                         )
         for function, entity, _operation_id, outputs, _dependencies in self._graph_operations:
             for output in outputs:
@@ -293,7 +291,7 @@ class FeatureGraph(GraphBase):
 
         def feature_meta(
             name: str,
-            function: spec.Function | None = None,
+            function: resolved.Function | None = None,
             entity: str | None = None,
             data_type: str | None = None,
         ) -> models.FeatureNode:

{uptimely_core-0.1.0/src/uptimely/analytics → uptimely_core-0.2.0.dev0/src/uptimely/analytics/feature_graph}/models.py

@@ -1,11 +1,8 @@
 import dataclasses
 
-from uptimely import spec
+from uptimely import render
 
-
-def _filled_fields(**fields: object) -> dict:
-    """Return fields with values useful for graph rendering."""
-    return {key: value for key, value in fields.items() if value is not None}
+from .. import resolved
 
 
 @dataclasses.dataclass(frozen=True)
@@ -15,7 +12,7 @@ class FunctionNode:
     name: str
     features: tuple[str, ...]
     entity: str | None
-    function: spec.Function | None = dataclasses.field(default=None, compare=False, hash=False)
+    function: resolved.Function | None = dataclasses.field(default=None, compare=False, hash=False)
 
     @property
     def node_id(self) -> str:
@@ -29,9 +26,9 @@ class FunctionNode:
     def __repr__(self) -> str:
         return self.name
 
-    def to_render_data(self, node_type: str = "function") -> dict:
+    def to_render_data(self, node_type: str = "function") -> dict[str, object]:
         """Return display metadata for rendering this function node."""
-        return _filled_fields(
+        return render.filled_fields(
             node_type=node_type,
             is_function=True,
             label=self.name,
@@ -77,9 +74,9 @@ class FeatureNode:
         """Whether this feature is both produced and consumed by the graph."""
         return self.is_input and self.is_output
 
-    def to_render_data(self, node_type: str) -> dict:
+    def to_render_data(self, node_type: str) -> dict[str, object]:
         """Return display metadata for rendering this feature node."""
-        return _filled_fields(
+        return render.filled_fields(
             node_type=node_type,
             is_function=False,
             label=self.name,

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

@@ -0,0 +1 @@
+"""Analytics JSON document encoding and I/O."""

uptimely_core-0.2.0.dev0/src/uptimely/analytics/json/codec.py

@@ -0,0 +1,42 @@
+"""JSON serialization helpers for analytics models."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import typing
+
+from uptimely import storage as storage_module
+
+if typing.TYPE_CHECKING:
+    from .. import model as analytics_model
+
+
+def load_document(path: str | pathlib.Path) -> dict[str, typing.Any]:
+    """Read one JSON document, rejecting unsupported multi-file definitions."""
+    if storage_module.Storage.is_dir(path):
+        path = storage_module.Storage.join(path, "analytics.json")
+    analytics_definition = json.loads(storage_module.Storage.read(path))
+    if analytics_definition.get("includes", []) or analytics_definition.get("external_specs", []):
+        raise ValueError("Analytics must be defined in a single JSON file")
+    return analytics_definition
+
+
+def to_document(analytics_definition: analytics_model.Analytics) -> dict[str, typing.Any]:
+    """Encode document models using the analytics document's identifier rules."""
+    payload = analytics_definition.model_dump(exclude_none=False)
+    for entity_id, entity in analytics_definition.entities.items():
+        serialized_entity = payload["entities"][entity_id]
+        for index, dataset in enumerate(entity.datasets):
+            serialized_entity["datasets"][index]["id"] = dataset.id
+    return payload
+
+
+def write_document(
+    analytics_definition: analytics_model.Analytics, path: str | pathlib.Path
+) -> str:
+    """Write an analytics document without mutating the source model."""
+    target = pathlib.Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(to_document(analytics_definition), indent=2), encoding="utf-8")
+    return str(target)

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

@@ -0,0 +1,48 @@
+"""Analytics document models, independent of their authoring format."""
+
+from .analytics import SUPPORTED_ANALYTICS_VERSION, Analytics
+from .common import (
+    AnalyticsSource,
+    Argument,
+    Binding,
+    BindingArgument,
+    Dimension,
+    StrictModel,
+)
+from .dataset import (
+    Dataset,
+    Entity,
+    Feature,
+    Mapping,
+    MappingFeatures,
+    Order,
+    RowScope,
+)
+from .functions import (
+    FUNCTION_OPERATIONS,
+    FUNCTION_TYPES,
+    FunctionCatalog,
+    FunctionTemplate,
+)
+
+__all__ = [
+    "FUNCTION_OPERATIONS",
+    "FUNCTION_TYPES",
+    "SUPPORTED_ANALYTICS_VERSION",
+    "Analytics",
+    "AnalyticsSource",
+    "Argument",
+    "Binding",
+    "BindingArgument",
+    "Dataset",
+    "Dimension",
+    "Entity",
+    "Feature",
+    "FunctionCatalog",
+    "FunctionTemplate",
+    "Mapping",
+    "MappingFeatures",
+    "Order",
+    "RowScope",
+    "StrictModel",
+]