operonx 0.6.2__py3-none-any.whl

operonx/__init__.py

@@ -0,0 +1,131 @@
+"""Operon — high-performance workflow engine for AI applications.
+
+Operon runs anything as a workflow — from IO-bound tasks like LLMs and
+agents to CPU-bound workloads. Inspired by Airflow operators, it enforces
+clear, consistent conventions for building scalable async workflows.
+
+Example::
+
+    from operonx import Operon, GraphOp, START, END, PARENT, op
+
+    @op
+    def double(x: int):
+        return {"result": x * 2}
+
+    with GraphOp(name="workflow") as graph:
+        step = double(x=PARENT["input"])
+        START >> step >> END
+
+    engine = Operon(graph)
+    result = await engine.run(inputs={"input": 5})
+
+Sub-namespaces:
+- ``operonx.core``       — engine, ops, state, tracing, registry
+- ``operonx.providers``  — LLM, embedding, reranker, ONNX backends
+- ``operonx.telemetry``  — Langfuse, OTEL, local tracers
+"""
+
+from pathlib import Path
+from typing import Optional, Union
+
+from operonx.core import (
+    END,
+    LOGGER,
+    PARENT,
+    PENDING,
+    START,
+    BranchOp,
+    FuncOp,
+    GraphOp,
+    Middleware,
+    Operon,
+    ParserOp,
+    graph,
+    op,
+)
+from operonx.core.registry import (
+    BOOTSTRAP_ENV_PATHS,
+    ResourceHub,
+)
+
+__version__ = "0.6.1"
+
+
+def bootstrap(
+    *,
+    resources: Optional[Union[str, Path]] = None,
+    env: bool = True,
+) -> Optional[ResourceHub]:
+    """One-line setup for ``.env`` and :class:`ResourceHub`.
+
+    - When ``env`` is ``True`` (default), load ``./.env`` from CWD using
+      ``python-dotenv`` (non-override; existing env wins). The path is
+      recorded in ``BOOTSTRAP_ENV_PATHS`` for later diagnostic messages.
+    - When ``resources`` is a path, install the hub via
+      :meth:`ResourceHub.from_yaml`.
+    - When ``resources`` is ``None``, call :meth:`ResourceHub.auto` —
+      which checks ``./resources.yaml`` and warns on miss.
+    - Idempotent: if a hub is already installed, return it unchanged.
+
+    Returns the installed hub, or ``None`` if no ``resources.yaml`` was
+    found and none was provided. Pure-compute graphs that don't need a
+    hub can ignore the return value.
+    """
+    if env:
+        _load_env_into_bootstrap()
+
+    if ResourceHub._instance is not None:
+        return ResourceHub._instance
+
+    if resources is not None:
+        hub = ResourceHub.from_yaml(resources)
+        ResourceHub.set_instance(hub)
+        return hub
+
+    return ResourceHub.auto()
+
+
+def _load_env_into_bootstrap() -> None:
+    """Load ``./.env`` from CWD if it exists; record the path.
+
+    Records the absolute path in ``BOOTSTRAP_ENV_PATHS`` regardless of
+    whether the file existed — this is what the env-var error message
+    surfaces, so users see exactly where ``.env`` was searched.
+    """
+    env_path = (Path.cwd() / ".env").resolve()
+    if env_path not in BOOTSTRAP_ENV_PATHS:
+        BOOTSTRAP_ENV_PATHS.append(env_path)
+    if not env_path.exists():
+        return
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return
+    load_dotenv(env_path, override=False)
+
+
+__all__ = [
+    # Engine
+    "Operon",
+    "Middleware",
+    # Core op types
+    "GraphOp",
+    "BranchOp",
+    "FuncOp",
+    "ParserOp",
+    # Decorators
+    "op",
+    "graph",
+    # Markers
+    "START",
+    "END",
+    "PARENT",
+    "PENDING",
+    # Logging
+    "LOGGER",
+    # Setup
+    "bootstrap",
+    "ResourceHub",
+    # Version
+    "__version__",
+]

operonx/core/__init__.py

@@ -0,0 +1,100 @@
+"""Operon core — workflow engine, ops, state, tracing, registry.
+
+Public surface re-exported from the submodules below. For top-level
+convenience imports (``from operonx import Operon``), see
+:mod:`operonx.__init__`.
+
+Example::
+
+    from operonx.core import Operon, GraphOp, START, END, PARENT
+    from operonx.core.ops import FuncOp
+
+    with GraphOp(name="workflow") as graph:
+        node = FuncOp(name="processor", ...)
+        START >> node >> END
+
+    engine = Operon(graph)
+    result = await engine.run(inputs={"key": "value"})
+    print(result["output"])   # workflow output
+    print(result["$state"])   # MemoryState for debugging
+"""
+
+from operonx.core.configs import EdgeConfig, EdgeType
+from operonx.core.engine import ExecutionHandle, Operon
+from operonx.core.loggings import LOGGER
+from operonx.core.media import Media
+from operonx.core.middleware import Middleware
+from operonx.core.ops import (
+    END,
+    PARENT,
+    PENDING,
+    START,
+    BaseOp,
+    BranchOp,
+    DummyOp,
+    FuncOp,
+    GraphOp,
+    ParserOp,
+    ParserType,
+    graph,
+    op,
+)
+from operonx.core.registry import (
+    REGISTRY,
+    CacheEntry,
+    ConfigEntry,
+    ConfigRegistry,
+    ConfigStorage,
+    HealthCheckResult,
+    JsonConfigStorage,
+    ResourceHub,
+    YamlConfigStorage,
+)
+from operonx.core.states import Cell, MemoryState, Ref, StateSchema
+from operonx.core.utils import Param
+
+__all__ = [
+    # Engine
+    "Operon",
+    "ExecutionHandle",
+    "Middleware",
+    # Op base / markers
+    "BaseOp",
+    "DummyOp",
+    "START",
+    "END",
+    "PARENT",
+    "PENDING",
+    # Op types
+    "GraphOp",
+    "BranchOp",
+    "FuncOp",
+    "ParserOp",
+    "ParserType",
+    # Decorators
+    "op",
+    "graph",
+    # State
+    "StateSchema",
+    "MemoryState",
+    "Ref",
+    "Cell",
+    # Configs / params
+    "EdgeConfig",
+    "EdgeType",
+    "Param",
+    # Multimodal
+    "Media",
+    # Logging
+    "LOGGER",
+    # Registry
+    "ResourceHub",
+    "ConfigRegistry",
+    "ConfigEntry",
+    "CacheEntry",
+    "REGISTRY",
+    "HealthCheckResult",
+    "ConfigStorage",
+    "YamlConfigStorage",
+    "JsonConfigStorage",
+]

operonx/core/configs/__init__.py

@@ -0,0 +1,15 @@
+"""Config types for the workflow graph.
+
+- ``OpType``     — enum of op categories (func, branch, graph, llm, ...)
+- ``EdgeConfig`` — config for edges between ops
+- ``EdgeType``   — edge kinds (normal, lookback, condition)
+"""
+
+from .edge_config import EdgeConfig, EdgeType
+from .op_config import OpType
+
+__all__ = [
+    "OpType",
+    "EdgeConfig",
+    "EdgeType",
+]

operonx/core/configs/edge_config.py

@@ -0,0 +1,25 @@
+"""Các kiểu config edge cho operonx."""
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+EdgeType = Literal["normal", "lookback", "condition"]
+
+
+class EdgeConfig(BaseModel):
+    """Config cho các edge giữa các node trong workflow graph.
+
+    Attributes:
+        from_node: Tên node nguồn
+        to_node: Tên node đích
+        type: Loại edge (normal, lookback, condition)
+        soft: Nếu True, edge này không được tính vào ready_count.
+              Dùng cho các đầu ra nhánh khi chỉ một nhánh được thực thi.
+              Được tạo bằng toán tử > thay vì >>
+    """
+
+    from_node: str
+    to_node: str
+    type: EdgeType = "normal"
+    soft: bool = False

operonx/core/configs/op_config.py

@@ -0,0 +1,34 @@
+"""Các kiểu và class config node cho operonx."""
+
+from typing import Literal
+
+OpType = Literal[
+    # Node dữ liệu
+    "data",
+    # Node AI/ML
+    "llm",
+    "embedding",
+    "rerank",
+    # Node điều khiển luồng
+    "branch",
+    "for",
+    "while",
+    "stream",
+    # Node xử lý
+    "code",
+    "lambda",
+    "parser",
+    "prompt",
+    "doc-processor",
+    # Node database/storage
+    "milvus",
+    "mongo",
+    "s3",
+    # Node đặc biệt
+    "graph",
+    "default",
+    "dummy",
+    "tool-executor",
+    "mcp",
+]
+"""Các loại node được hỗ trợ trong workflow graph."""