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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uptimely-core
-Version: 0.2.0.dev0
+Version: 0.2.0.dev1
 Summary: Manage data-driven numerical analytics with complex dependencies at scale
 License-Expression: MIT
 License-File: LICENSE
@@ -63,7 +63,9 @@ With pip:
 
 ```sh
 pip install uptimely-core
-uptimely examples download
+uptimely examples download --output examples
+uptimely project build --project-root examples/pump_analytics
+uptimely engine run --project-root examples/pump_analytics
 uptimely explorer serve --project-root examples/pump_analytics
 ```
 
@@ -71,11 +73,12 @@ With Poetry, from your Poetry project:
 
 ```sh
 poetry add uptimely-core
-poetry run uptimely examples download
+poetry run uptimely examples download --output examples
+poetry run uptimely project build --project-root examples/pump_analytics
+poetry run uptimely engine run --project-root examples/pump_analytics
 poetry run uptimely explorer serve --project-root examples/pump_analytics
 ```
 
-More use cases in [examples](examples/README.md). Explore the examples files, generated resources and modify for the needs of your own project.
 
 ## Documentation
 

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

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "uptimely-core"
-version = "0.2.0.dev0"
+version = "0.2.0.dev1"
 description = "Manage data-driven numerical analytics with complex dependencies at scale"
 authors = [{ name = "Mikael Ahonen", email = "mikael.ahonen@uptimely.ai" }]
 license = "MIT"

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

@@ -33,7 +33,9 @@ With pip:
 
 ```sh
 pip install uptimely-core
-uptimely examples download
+uptimely examples download --output examples
+uptimely project build --project-root examples/pump_analytics
+uptimely engine run --project-root examples/pump_analytics
 uptimely explorer serve --project-root examples/pump_analytics
 ```
 
@@ -41,11 +43,12 @@ With Poetry, from your Poetry project:
 
 ```sh
 poetry add uptimely-core
-poetry run uptimely examples download
+poetry run uptimely examples download --output examples
+poetry run uptimely project build --project-root examples/pump_analytics
+poetry run uptimely engine run --project-root examples/pump_analytics
 poetry run uptimely explorer serve --project-root examples/pump_analytics
 ```
 
-More use cases in [examples](examples/README.md). Explore the examples files, generated resources and modify for the needs of your own project.
 
 ## Documentation
 

{uptimely_core-0.2.0.dev0 → uptimely_core-0.2.0.dev1}/src/uptimely/__init__.py

@@ -1,25 +1,25 @@
 """Public package namespace for uptimely."""
 
-from .analytics import (
-    Analytics,
+from .compiler import CallableGraph, CallableNode, Compiler, ExecutionPlan
+from .engine import Engine
+from .spec import (
     Call,
     Dimension,
     Entity,
     FeatureGraph,
     Function,
-    PreparedAnalytics,
-    PythonAnalytics,
+    PreparedSpec,
+    PythonSpec,
+    Spec,
     SubGraph,
     from_python,
-    load_analytics,
-    prepare_analytics,
+    load_spec,
+    prepare_spec,
     write_document,
 )
-from .compiler import CallableGraph, CallableNode, Compiler, ExecutionPlan
-from .engine import Engine
 
 __all__ = [
-    "Analytics",
+    "Spec",
     "Call",
     "CallableGraph",
     "CallableNode",
@@ -28,11 +28,11 @@ __all__ = [
     "Entity",
     "ExecutionPlan",
     "Function",
-    "PythonAnalytics",
-    "PreparedAnalytics",
+    "PythonSpec",
+    "PreparedSpec",
     "from_python",
-    "load_analytics",
-    "prepare_analytics",
+    "load_spec",
+    "prepare_spec",
     "write_document",
     "SubGraph",
     "FeatureGraph",

{uptimely_core-0.2.0.dev0 → uptimely_core-0.2.0.dev1}/src/uptimely/cli/cli.py

@@ -2,10 +2,9 @@
 
 import argparse
 
-from uptimely.cli import analytics, engine, examples, explorer, plan
+from uptimely.cli import engine, examples, explorer, project, spec
 
 download_examples = examples.download_examples
-build_explorer = explorer.build_explorer
 serve_explorer = explorer.serve_explorer
 
 
@@ -15,22 +14,22 @@ def main() -> None:
     commands = parser.add_subparsers(dest="command", required=True)
     examples.configure_parser(commands.add_parser("examples", help="Manage example projects"))
     explorer.configure_parser(
-        commands.add_parser("explorer", help="Explore analytics, lineage, and execution plans")
+        commands.add_parser("explorer", help="Explore spec, lineage, and execution plans")
     )
-    analytics.configure_parser(
-        commands.add_parser("analytics", help="Export and inspect analytics")
+    spec.configure_parser(
+        commands.add_parser("spec", help="Inspect specs and feature dependencies")
     )
-    plan.configure_parser(commands.add_parser("plan", help="Build execution plans"))
+    project.configure_parser(commands.add_parser("project", help="Build project resources"))
     engine.configure_parser(commands.add_parser("engine", help="Run analytics workflows"))
     args = parser.parse_args()
     if args.command == "examples":
         examples.run(args, parser)
     elif args.command == "explorer":
         explorer.run(args, parser)
-    elif args.command == "analytics":
-        analytics.run(args, parser)
-    elif args.command == "plan":
-        plan.run(args, parser)
+    elif args.command == "spec":
+        spec.run(args, parser)
+    elif args.command == "project":
+        project.run(args, parser)
     else:
         engine.run(args, parser)
 

uptimely_core-0.2.0.dev1/src/uptimely/cli/common.py

@@ -0,0 +1,38 @@
+"""Shared project paths and spec loading for CLI commands."""
+
+import argparse
+import pathlib
+
+from uptimely import spec
+from uptimely.project.build import prepare_project_root
+
+
+def configure_project_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add spec, import-root, feature-selection, and diagnostic options."""
+    parser.add_argument(
+        "--spec",
+        type=pathlib.Path,
+        help="Spec JSON to inspect (default: spec from the active project build)",
+    )
+    parser.add_argument(
+        "--project-root",
+        type=pathlib.Path,
+        help="Root for importing function entrypoints and resolving default paths",
+    )
+    parser.add_argument(
+        "--features", nargs="+", help="Select output features and their dependencies"
+    )
+    parser.add_argument("--verbose", action="store_true", help="Print diagnostic details")
+
+
+def project_path(
+    path: pathlib.Path | None, project_root: pathlib.Path | None, default: pathlib.Path
+) -> pathlib.Path:
+    """Resolve a default beneath the project root, preserving explicit paths."""
+    return path if path is not None else (project_root or pathlib.Path()) / default
+
+
+def load_spec(path: pathlib.Path, project_root: pathlib.Path) -> spec.Spec:
+    """Load a spec document with project functions on the import path."""
+    prepare_project_root(project_root)
+    return spec.load_spec(path)

{uptimely_core-0.2.0.dev0 → uptimely_core-0.2.0.dev1}/src/uptimely/cli/engine.py

@@ -7,8 +7,8 @@ import typing
 import pydantic
 
 from uptimely import engine as engine_module
+from uptimely import project
 from uptimely.cli import common, plan
-from uptimely.compiler import plan as plan_module
 
 
 class EngineSettings(pydantic.BaseModel):
@@ -23,68 +23,52 @@ class EngineSettings(pydantic.BaseModel):
 def configure_parser(parser: argparse.ArgumentParser) -> None:
     """Configure the engine run action."""
     actions = parser.add_subparsers(dest="action", required=True)
-    execute = actions.add_parser("run", help="Compile and execute an analytics workflow")
-    common.configure_project_arguments(execute)
+    execute = actions.add_parser("run", help="Execute the active project's saved build")
     execute.add_argument(
-        "--compile",
-        choices=["true", "false"],
-        default="true",
-        help="Compile analytics first (default: true); false loads --plan",
+        "--project-root",
+        type=pathlib.Path,
+        help="Project root containing the active build and function entrypoints",
     )
     execute.add_argument(
-        "--plan",
-        type=pathlib.Path,
-        help=(
-            "Saved plan JSON (default: _generated/compile/execution_plan.json under --project-root)"
-        ),
+        "--verbose", action="store_true", help="Print execution stages and dataset details"
     )
     execute.add_argument(
         "--config",
         type=pathlib.Path,
         help=(
             "Backend settings and runtime bindings "
-            "(default: config/engine.json under --project-root)"
+            f"(default: {project.ENGINE_CONFIG_FILE} under --project-root)"
         ),
     )
 
 
 def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
-    """Execute a compiled or saved plan and report failures explicitly."""
-    if args.compile == "false" and (args.analytics is not None or args.features is not None):
-        parser.error("--analytics and --features require --compile true")
-    if args.compile == "true" and args.plan is not None:
-        parser.error("--plan requires --compile false")
+    """Execute the active saved plan and report failures explicitly."""
     root = args.project_root or pathlib.Path.cwd()
-    config = common.project_path(args.config, args.project_root, common.ENGINE_CONFIG_PATH)
-    analytics_definition = common.project_path(
-        args.analytics, args.project_root, common.GENERATED_ANALYTICS_PATH
-    )
-    plan_path = common.project_path(args.plan, args.project_root, common.GENERATED_PLAN_PATH)
+    config = common.project_path(args.config, args.project_root, project.ENGINE_CONFIG_FILE)
     try:
         common.prepare_project_root(root)
-        settings = EngineSettings.model_validate_json(config.read_text(encoding="utf-8"))
-        execution_plan = (
-            plan.compile_plan(analytics_definition, root, args.features)
-            if args.compile == "true"
-            else plan_module.ExecutionPlan.from_json(plan_path)
-        )
-        result = engine_module.Engine(
-            execution_plan, config=settings.backend, bind=settings.bind
-        ).execute()
-        if result.failures:
-            failures = "; ".join(result.failures.values())
-            raise RuntimeError(f"Engine flow failed: {failures}")
+        with project.read_build_bundle(root) as bundle:
+            settings = EngineSettings.model_validate_json(config.read_text(encoding="utf-8"))
+            execution_plan = bundle.execution_plan
+            result = engine_module.Engine(
+                execution_plan, config=settings.backend, bind=settings.bind
+            ).execute()
+            if result.failures:
+                failures = "; ".join(result.failures.values())
+                raise RuntimeError(f"Engine flow failed: {failures}")
     except (OSError, ValueError, ImportError, AttributeError, TypeError, RuntimeError) as error:
         parser.exit(1, f"uptimely: error: {error}\n")
     calculated_features = sorted({feature_id for _, _, feature_id in result.calculated_outputs})
+    scope = (
+        "all features"
+        if bundle.manifest.features is None
+        else f"selected features: {', '.join(bundle.manifest.features)}"
+    )
     print("Engine completed the flow")
+    print(f"Build scope: {scope}")
     print(f"{len(execution_plan.callables)} callables")
     print("Calculated features: " + ", ".join(calculated_features))
-    print(
-        f"Analytics: {analytics_definition}"
-        if args.compile == "true"
-        else f"Execution plan: {plan_path}"
-    )
     if args.verbose:
         plan.print_stages(execution_plan)
         print("\nDataset registry")

uptimely_core-0.2.0.dev1/src/uptimely/cli/explorer.py

@@ -0,0 +1,92 @@
+"""Command-line tools for building and serving the analytics explorer."""
+
+import argparse
+import functools
+import pathlib
+from http import server as http_server
+
+from uptimely import project
+
+
+def serve_explorer(
+    directory: pathlib.Path,
+    host: str = "127.0.0.1",
+    port: int = 8001,
+    scope: str = "all features",
+) -> None:
+    """Serve a saved analytics explorer website for local preview.
+
+    Args:
+        directory: Saved website directory containing an index.html file.
+        host: Address to bind; defaults to localhost.
+        port: TCP port; defaults to 8001. Zero selects an available port.
+        scope: Human-readable scope of the saved execution plan.
+
+    Raises:
+        NotADirectoryError: The website directory does not exist or is not a directory.
+        FileNotFoundError: The website index is missing.
+        ValueError: The port is outside the valid TCP range.
+        OSError: The server cannot bind to the requested address.
+    """
+    directory = directory.resolve()
+    if not directory.is_dir():
+        raise NotADirectoryError(f"Website directory does not exist: {directory}")
+    index = directory / project.EXPLORER_INDEX_FILE.name
+    if not index.is_file():
+        raise FileNotFoundError(
+            f"Website index not found: {index}. Generate it with 'uptimely project build'."
+        )
+    if not 0 <= port <= 65535:
+        raise ValueError("Port must be between 0 and 65535.")
+    handler = functools.partial(http_server.SimpleHTTPRequestHandler, directory=str(directory))
+    with http_server.ThreadingHTTPServer((host, port), handler) as server:
+        print(
+            f"Serving analytics explorer from {directory} at "
+            f"http://{host}:{server.server_port}/ (build scope: {scope}; Ctrl+C to stop)",
+            flush=True,
+        )
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            print("\nSpec explorer server stopped.")
+
+
+def _port(value: str) -> int:
+    """Parse a valid TCP port for the CLI."""
+    try:
+        port = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("Port must be an integer.") from error
+    if not 0 <= port <= 65535:
+        raise argparse.ArgumentTypeError("Port must be between 0 and 65535.")
+    return port
+
+
+def configure_parser(parser: argparse.ArgumentParser) -> None:
+    """Configure the Explorer serve action."""
+    actions = parser.add_subparsers(dest="action", required=True)
+    serve = actions.add_parser("serve", help="Serve the active build's saved website")
+    serve.add_argument(
+        "--project-root",
+        type=pathlib.Path,
+        help="Project root containing the active build",
+    )
+    serve.add_argument("--host", default="127.0.0.1", help="Bind address (default: 127.0.0.1)")
+    serve.add_argument(
+        "--port", type=_port, default=8001, help="TCP port (default: 8001; 0 selects a free port)"
+    )
+
+
+def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Serve the active build's validated, saved Explorer website."""
+    project_root = (args.project_root or pathlib.Path.cwd()).resolve()
+    try:
+        with project.read_build_bundle(project_root) as bundle:
+            scope = (
+                "all features"
+                if bundle.manifest.features is None
+                else f"selected features: {', '.join(bundle.manifest.features)}"
+            )
+            serve_explorer(bundle.explorer_path, args.host, args.port, scope)
+    except (OSError, ValueError, RuntimeError) as error:
+        parser.exit(1, f"uptimely: error: {error}\n")

uptimely_core-0.2.0.dev1/src/uptimely/cli/plan.py

@@ -0,0 +1,18 @@
+"""Display execution plan stages in the CLI."""
+
+from uptimely.compiler import plan as plan_module
+
+
+def print_stages(plan: plan_module.ExecutionPlan) -> None:
+    """Print execution stages and their function dependencies."""
+    callables_by_id = {callable.id: callable for callable in plan.callables}
+    print("\nExecution stages")
+    for stage_number, stage in enumerate(plan.execution_stages, 1):
+        print(f"Stage {stage_number}")
+        for callable in stage:
+            dependencies = [
+                callables_by_id[dependency_id].function_id
+                for dependency_id in callable.dependency_ids
+            ]
+            suffix = f" <- [{', '.join(dependencies)}]" if dependencies else ""
+            print(f"  {callable.function_id}({callable.entity_id}) -> {callable.output}{suffix}")

uptimely_core-0.2.0.dev1/src/uptimely/cli/project.py

@@ -0,0 +1,62 @@
+"""Command-line orchestration for building generated project resources."""
+
+import argparse
+import pathlib
+
+from uptimely.project import build as project_build
+
+
+def configure_parser(parser: argparse.ArgumentParser) -> None:
+    """Configure the project build action."""
+    actions = parser.add_subparsers(dest="action", required=True)
+    build = actions.add_parser(
+        "build",
+        help="Build and publish a complete project bundle without running workflows",
+    )
+    source = build.add_mutually_exclusive_group()
+    source.add_argument(
+        "--entrypoint",
+        metavar="MODULE:ATTRIBUTE",
+        help="Importable module and attribute containing a PythonSpec instance",
+    )
+    source.add_argument(
+        "--spec",
+        type=pathlib.Path,
+        help="Source spec JSON path (overrides standard source discovery)",
+    )
+    build.add_argument(
+        "--project-root",
+        type=pathlib.Path,
+        help="Root added to the import path and used to resolve the output bundle",
+    )
+    build.add_argument(
+        "--features",
+        nargs="+",
+        metavar="FEATURE",
+        help="Select output features and their dependencies",
+    )
+
+
+def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Build and publish a complete project bundle."""
+    root = args.project_root or pathlib.Path.cwd()
+    try:
+        bundle = project_build.build_project(
+            root,
+            entrypoint=args.entrypoint,
+            source=args.spec,
+            features=args.features,
+        )
+    except (
+        project_build.BuildLockError,
+        project_build.ProjectBuildError,
+        OSError,
+        ValueError,
+    ) as error:
+        parser.exit(1, f"uptimely: error: {error}\n")
+    scope = (
+        "all features" if bundle.manifest.features is None else ", ".join(bundle.manifest.features)
+    )
+    print(f"Build scope: {scope}")
+    print(f"Build bundle: {bundle.root}")
+    print(f"Compiled {len(bundle.execution_plan.callables)} callables")

uptimely_core-0.2.0.dev1/src/uptimely/cli/spec.py

@@ -0,0 +1,39 @@
+"""Command-line tools for inspecting spec features."""
+
+import argparse
+import pathlib
+
+from uptimely import project
+from uptimely.cli import common
+from uptimely.spec import feature_graph
+
+
+def configure_parser(parser: argparse.ArgumentParser) -> None:
+    """Configure spec feature-graph inspection."""
+    actions = parser.add_subparsers(dest="action", required=True)
+    graph = actions.add_parser("feature-graph", help="Inspect feature dependencies")
+    common.configure_project_arguments(graph)
+
+
+def run(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Print feature graph summaries and trees."""
+    project_root = args.project_root or pathlib.Path.cwd()
+    try:
+        if args.spec is None:
+            with project.read_build_bundle(project_root) as bundle:
+                spec_definition = common.load_spec(bundle.spec_path, project_root)
+        else:
+            spec_definition = common.load_spec(args.spec, project_root)
+        graph = feature_graph.FeatureGraph(spec_definition)
+        subset = graph.subset(args.features) if args.features is not None else None
+        print(f"Feature graph: {len(graph.feature_names)} features")
+        if subset is not None:
+            print(f"Selected feature subset: {len(subset.feature_names)} features")
+        if args.verbose:
+            print("\nFeature graph")
+            graph.print_graph()
+            if subset is not None:
+                print("\nSelected feature subset")
+                subset.print_graph()
+    except (OSError, ValueError, ImportError, AttributeError, TypeError, RuntimeError) as error:
+        parser.exit(1, f"uptimely: error: {error}\n")

{uptimely_core-0.2.0.dev0 → uptimely_core-0.2.0.dev1}/src/uptimely/compiler/__init__.py

@@ -1,4 +1,4 @@
-"""Compile analytics into portable execution plans."""
+"""Compile spec into portable execution plans."""
 
 from .callable_node import CallableNode
 from .compiler import Compiler, ExecutionPlan

{uptimely_core-0.2.0.dev0 → uptimely_core-0.2.0.dev1}/src/uptimely/compiler/callable_node.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import dataclasses
 
-from uptimely import analytics, render, row_context
+from uptimely import render, row_context, spec
 
 
 @dataclasses.dataclass(frozen=True)
@@ -17,7 +17,7 @@ class CallableNode:
     mapping_id: str | None = None
     output_features: tuple[str, ...] = ()
     args: dict[str, object] = dataclasses.field(default_factory=dict, compare=False, hash=False)
-    callable: analytics.Call | None = dataclasses.field(default=None, compare=False, hash=False)
+    callable: spec.Call | None = dataclasses.field(default=None, compare=False, hash=False)
     row_context: row_context.RowContext | None = dataclasses.field(
         default=None, compare=False, hash=False
     )