juturna 1.0.2__tar.gz

juturna-1.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Antonio Bevilacqua
+
+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.

juturna-1.0.2/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.3
+Name: juturna
+Version: 1.0.2
+Summary: Juturna core library
+License: MIT
+Author: Antonio Bevilacqua
+Author-email: b3by.in.th3.sky@gmail.com
+Maintainer: Antonio Bevilacqua
+Maintainer-email: b3by.in.th3.sky@gmail.com
+Requires-Python: >=3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Provides-Extra: dev
+Provides-Extra: httpwrapper
+Provides-Extra: pipebuilder
+Requires-Dist: av (>=14.2.0,<15.0.0)
+Requires-Dist: fastapi-cli[httpwrapper] (>=0.0.7,<0.0.8) ; extra == "httpwrapper"
+Requires-Dist: fastapi[httpwrapper] (>=0.115.12,<0.116.0) ; extra == "httpwrapper"
+Requires-Dist: furo[dev] (>=2025.9.25,<2026.0.0) ; extra == "dev"
+Requires-Dist: numpy (==2.2.3)
+Requires-Dist: prompt_toolkit[pipebuilder] (>=3.0.52,<4.0.0) ; extra == "pipebuilder"
+Requires-Dist: pytest[dev] (>=8.3.5,<9.0.0) ; extra == "dev"
+Requires-Dist: requests (==2.32.3)
+Requires-Dist: rich[pipebuilder] (>=13.8.1,<14.0.0) ; extra == "pipebuilder"
+Requires-Dist: sphinx-autoapi[dev] (>=3.6.0,<4.0.0) ; extra == "dev"
+Requires-Dist: sphinx-autobuild[dev] (>=2024.10.3,<2025.0.0) ; extra == "dev"
+Requires-Dist: sphinx-design[dev] (>=0.6.1,<0.7.0) ; extra == "dev"
+Requires-Dist: sphinx-new-tab-link[dev] (>=0.8.0,<0.9.0) ; extra == "dev"
+Requires-Dist: sphinx[dev] (>=8.2.3,<9.0.0) ; extra == "dev"
+Requires-Dist: sphinxcontrib-apidoc[dev] (>=0.5.0,<0.6.0) ; extra == "dev"
+Requires-Dist: sphinxcontrib-napoleon[dev] (>=0.7,<0.8) ; extra == "dev"
+Requires-Dist: websockets (>=15.0.1,<16.0.0)
+Project-URL: Changelog, https://github.com/meetecho/juturna/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://meetecho.github.io/juturna/index.html
+Project-URL: Homepage, https://github.com/meetecho/juturna
+Project-URL: Issues, https://github.com/meetecho/juturna/issues
+Project-URL: Repository, https://github.com/meetecho/juturna
+Description-Content-Type: text/markdown
+
+# Juturna – Real-time AI Pipeline Framework
+<p align="center"><img src="https://raw.githubusercontent.com/meetecho/juturna/main/docs/source/_static/img/logo_dark_alt.svg" width="30%">
+<br>
+<img src="https://img.shields.io/github/license/meetecho/juturna?style=for-the-badge"> <img src="https://img.shields.io/github/stars/meetecho/juturna?style=for-the-badge"> <img src="https://img.shields.io/github/forks/meetecho/juturna?style=for-the-badge"> <img src="https://img.shields.io/github/issues/meetecho/juturna?style=for-the-badge">
+</p>
+
+## :seedling: Important to know
+Juturna is actively evolving with exciting new features and improvements being
+added regularly. We're using semantic versioning to clearly communicate any
+breaking changes between releases, so you can upgrade with confidence. Juturna
+is perfect for experimentation and prototyping today, and we're working toward
+production-ready stability with each release. So, if you plan to deploy it in
+production, make sure you are comfortable managing potential updates and
+adjustments.
+
+## At a glance
+
+**Juturna** is a data pipeline library written in Python. It is particularly
+useful for fast prototyping multimedia, **real-time** data applications, as
+well as exploring and testing AI models, in a modular and flexible fashion.
+
+Among its many features, there are a few keypoints to highligh about Juturna:
+
+* :zap: **Real-Time Streaming:** continuouusly process audio, video and
+  arbitrary data streams
+* :electric_plug: **Modularity:** create your own nodes and share them through
+  the Juturna hub
+* :link: **Composable workloads:** design pipelines to solve complex tasks in
+  minutes
+* 🚀 **Parallelism & Batching:** parallel, non-blocking execution for high
+  throughput
+* 📊 **Observability:** built-in logging and metrics support
+
+[documentation](https://meetecho.github.io/juturna/index.html) | [contribute](https://github.com/meetecho/juturna/blob/main/CONTRIBUTING.md) | [meetecho](https://www.meetecho.com/en/)
+
+## Overview
+
+A **pipeline** can simply be defined as a collection of **nodes**.
+
+Each **node** acquires a piece of data from its parents and, after performing a
+single task, provide its output to its children. In this sense, a Juturna
+pipeline is nothing else but a DAG, where root nodes have an in-degree of 0
+(this is not technically the case, but we’ll skip it for now), and every other
+node has an in-degree of 1 or more.
+
+An example of one of our pipelines, currently in use for live audio
+transcription and summarisation is shown here.
+
+<p align="center"><img src="https://raw.githubusercontent.com/meetecho/juturna/main/assets/img/pipeline_example.png"></p>
+
+Whilst Juturna ships with a number of built-in nodes (mainly source and sink
+nodes), you can implement your own nodes with ease, and share them so others
+can use them too.
+
+To know more about the Juturna internals, please refer to the full
+documentation.
+
+## Installation
+
+The following dependencies are required to use Juturna:
+
+- ``python >= 3.12``
+- system libraries ``libsm6``, ``libext6``, ``ffmpeg``
+
+:information_source: Current Python building version is 3.12. The library still
+has to be tested on Python 3.13 and later with GIL disabled.
+
+
+Juturna is currently available as a opensource codebase, but not yet published
+on PyPi.  To install it on your system, first clone the repository, then use
+pip to install it (assuming you are working in a virtual environment):
+
+```
+(venv) $ git clone https://github.com/meetecho/juturna
+(venv) $ pip install ./juturna
+```
+
+In case you want to include all the development dependencies in the
+installation, specify the ``dev`` group:
+
+```
+(venv) $ pip install "./juturna[dev]"
+```
+
+To include the Juturna HTTP wrapper, include the ``httpwrapper``:
+
+```
+(venv) $ pip install "./juturna[httpwrapper]"
+```
+
+Alternatively, you can manually install the required dependencies, and just
+import the juturna module from within the repository folder:
+
+```
+(venv) $ pip install av ffmpeg-python opencv-python numpy requests websockets
+(venv) $ python
+>>> import juturna as jt
+```
+
+### Dockerfile
+
+In the Juturna repository you will find a Dockerfile that can be used to create
+a base Juturna image. To build it, symply navigate within the repo folder and
+run:
+
+```
+$ docker build -t juturna:latest .
+```
+
+## Contributing
+
+Please read [`CONTRIBUTING.md`](https://github.com/meetecho/juturna/blob/main/CONTRIBUTING.md) for:
+
+* Branching & PR workflow 
+* Code style & linting
+* Issue triage (TBD)
+* Issue & PR templates and a Code of Conduct are provided (TBD)
+* Signing CRA
+
+## Changelog
+
+All notable changes are documented in [`CHANGELOG.md`](https://github.com/meetecho/juturna/blob/main/CHANGELOG.md)
+following [Semantic Versioning](https://semver.org).
+
+## External Docs & Support
+
+Coming soon!
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](https://github.com/meetecho/juturna/blob/main/LICENSE) for details.
+

juturna-1.0.2/README.md

@@ -0,0 +1,131 @@
+# Juturna – Real-time AI Pipeline Framework
+<p align="center"><img src="https://raw.githubusercontent.com/meetecho/juturna/main/docs/source/_static/img/logo_dark_alt.svg" width="30%">
+<br>
+<img src="https://img.shields.io/github/license/meetecho/juturna?style=for-the-badge"> <img src="https://img.shields.io/github/stars/meetecho/juturna?style=for-the-badge"> <img src="https://img.shields.io/github/forks/meetecho/juturna?style=for-the-badge"> <img src="https://img.shields.io/github/issues/meetecho/juturna?style=for-the-badge">
+</p>
+
+## :seedling: Important to know
+Juturna is actively evolving with exciting new features and improvements being
+added regularly. We're using semantic versioning to clearly communicate any
+breaking changes between releases, so you can upgrade with confidence. Juturna
+is perfect for experimentation and prototyping today, and we're working toward
+production-ready stability with each release. So, if you plan to deploy it in
+production, make sure you are comfortable managing potential updates and
+adjustments.
+
+## At a glance
+
+**Juturna** is a data pipeline library written in Python. It is particularly
+useful for fast prototyping multimedia, **real-time** data applications, as
+well as exploring and testing AI models, in a modular and flexible fashion.
+
+Among its many features, there are a few keypoints to highligh about Juturna:
+
+* :zap: **Real-Time Streaming:** continuouusly process audio, video and
+  arbitrary data streams
+* :electric_plug: **Modularity:** create your own nodes and share them through
+  the Juturna hub
+* :link: **Composable workloads:** design pipelines to solve complex tasks in
+  minutes
+* 🚀 **Parallelism & Batching:** parallel, non-blocking execution for high
+  throughput
+* 📊 **Observability:** built-in logging and metrics support
+
+[documentation](https://meetecho.github.io/juturna/index.html) | [contribute](https://github.com/meetecho/juturna/blob/main/CONTRIBUTING.md) | [meetecho](https://www.meetecho.com/en/)
+
+## Overview
+
+A **pipeline** can simply be defined as a collection of **nodes**.
+
+Each **node** acquires a piece of data from its parents and, after performing a
+single task, provide its output to its children. In this sense, a Juturna
+pipeline is nothing else but a DAG, where root nodes have an in-degree of 0
+(this is not technically the case, but we’ll skip it for now), and every other
+node has an in-degree of 1 or more.
+
+An example of one of our pipelines, currently in use for live audio
+transcription and summarisation is shown here.
+
+<p align="center"><img src="https://raw.githubusercontent.com/meetecho/juturna/main/assets/img/pipeline_example.png"></p>
+
+Whilst Juturna ships with a number of built-in nodes (mainly source and sink
+nodes), you can implement your own nodes with ease, and share them so others
+can use them too.
+
+To know more about the Juturna internals, please refer to the full
+documentation.
+
+## Installation
+
+The following dependencies are required to use Juturna:
+
+- ``python >= 3.12``
+- system libraries ``libsm6``, ``libext6``, ``ffmpeg``
+
+:information_source: Current Python building version is 3.12. The library still
+has to be tested on Python 3.13 and later with GIL disabled.
+
+
+Juturna is currently available as a opensource codebase, but not yet published
+on PyPi.  To install it on your system, first clone the repository, then use
+pip to install it (assuming you are working in a virtual environment):
+
+```
+(venv) $ git clone https://github.com/meetecho/juturna
+(venv) $ pip install ./juturna
+```
+
+In case you want to include all the development dependencies in the
+installation, specify the ``dev`` group:
+
+```
+(venv) $ pip install "./juturna[dev]"
+```
+
+To include the Juturna HTTP wrapper, include the ``httpwrapper``:
+
+```
+(venv) $ pip install "./juturna[httpwrapper]"
+```
+
+Alternatively, you can manually install the required dependencies, and just
+import the juturna module from within the repository folder:
+
+```
+(venv) $ pip install av ffmpeg-python opencv-python numpy requests websockets
+(venv) $ python
+>>> import juturna as jt
+```
+
+### Dockerfile
+
+In the Juturna repository you will find a Dockerfile that can be used to create
+a base Juturna image. To build it, symply navigate within the repo folder and
+run:
+
+```
+$ docker build -t juturna:latest .
+```
+
+## Contributing
+
+Please read [`CONTRIBUTING.md`](https://github.com/meetecho/juturna/blob/main/CONTRIBUTING.md) for:
+
+* Branching & PR workflow 
+* Code style & linting
+* Issue triage (TBD)
+* Issue & PR templates and a Code of Conduct are provided (TBD)
+* Signing CRA
+
+## Changelog
+
+All notable changes are documented in [`CHANGELOG.md`](https://github.com/meetecho/juturna/blob/main/CHANGELOG.md)
+following [Semantic Versioning](https://semver.org).
+
+## External Docs & Support
+
+Coming soon!
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](https://github.com/meetecho/juturna/blob/main/LICENSE) for details.

juturna-1.0.2/juturna/__init__.py

@@ -0,0 +1,24 @@
+import juturna.names as names
+import juturna.components as components
+import juturna.nodes as nodes
+import juturna.utils as utils
+import juturna.hub as hub
+import juturna.meta as meta
+import juturna.payloads as payloads
+
+import juturna.utils.log_utils as log
+
+
+__app_name__ = 'juturna'
+__version__ = '0.1.0'
+
+__all__ = [
+    'names',
+    'components',
+    'nodes',
+    'utils',
+    'log',
+    'meta',
+    'hub',
+    'payloads'
+]

juturna-1.0.2/juturna/__main__.py

@@ -0,0 +1,30 @@
+import argparse
+import sys
+
+
+from juturna.cli import commands
+
+
+parser = argparse.ArgumentParser(
+    prog='juturna',
+    description=(
+        'Collection of simple CLI utilities to manage pipeline configuration '
+        'files and pipeline lifecycles.'
+    ))
+
+subparsers = parser.add_subparsers(
+    dest='command',
+    description='List of commands included in the juturna CLI')
+
+commands.register_all(subparsers)
+_ret = 0
+
+args = parser.parse_args()
+
+if command := args.command:
+    delattr(args, 'command')
+    _ret = commands.command(command)(args)
+else:
+    parser.print_help()
+
+sys.exit(_ret)

juturna-1.0.2/juturna/cli/_cli_utils.py

@@ -0,0 +1,23 @@
+import argparse
+import pathlib
+
+
+
+def _is_file_ok(file_path: str) -> str:
+    if not pathlib.Path(file_path).exists():
+        raise argparse.ArgumentTypeError(f'{file_path} does not exists')
+
+    if not pathlib.Path(file_path).is_file():
+        raise argparse.ArgumentTypeError(f'{file_path} is not a file')
+
+    return file_path
+
+
+def _is_dir_ok(dir_path: str) -> str:
+    if not pathlib.Path(dir_path).exists():
+        raise argparse.ArgumentTypeError(f'{dir_path} does not exists')
+
+    if not pathlib.Path(dir_path).is_dir():
+        raise argparse.ArgumentTypeError(f'{dir_path} is not a file')
+
+    return dir_path

juturna-1.0.2/juturna/cli/commands/__init__.py

@@ -0,0 +1,35 @@
+"""
+CLI registry
+
+Commands are registered based on whether their required modules are installed. A
+command for which its module fails to be imported will not be registered, so it
+will not be available in the command line.
+"""
+
+import importlib
+
+
+_MODULES = {
+    cmd: None for cmd in ['launch', 'validate', 'serve', 'create', 'stub']
+}
+
+
+def _safe_reg(module_name: str, subparsers):
+    try:
+        _MODULES[module_name] = importlib.import_module(
+            f'juturna.cli.commands.{module_name}'
+        )
+        _MODULES[module_name].setup_parser(subparsers)
+    except ModuleNotFoundError:
+        ...
+
+
+def register_all(subparsers):
+    """Register subparsers for all modules"""
+    for module in _MODULES:
+        _safe_reg(module, subparsers)
+
+
+def command(cmd_name: str):
+    """Return command caller function"""
+    return _MODULES[cmd_name]._execute

juturna-1.0.2/juturna/cli/commands/_common_pipe_parser.py

@@ -0,0 +1,27 @@
+import argparse
+
+from juturna.cli import _cli_utils
+
+
+def common_parser():
+    parser = argparse.ArgumentParser(add_help=False)
+
+    parser.add_argument(
+        '--log-level',
+        '-l',
+        type=str,
+        default='DEBUG',
+        choices=['NOTSET', 'DEBUG', 'INFO', 'WARNING', 'ERROR'],
+        help='set log level during pipeline execution'
+    )
+
+    parser.add_argument(
+        '--config',
+        '-c',
+        required=True,
+        metavar='FILE',
+        type=_cli_utils._is_file_ok,
+        help='pipeline json configuration file',
+    )
+
+    return parser

juturna-1.0.2/juturna/cli/commands/_create_tools.py

@@ -0,0 +1,74 @@
+import pathlib
+import tomllib
+
+
+_TYPE_MAP = {
+    bool: 'boolean',
+    int: 'integer',
+    float: 'float',
+    str: 'string',
+    dict: 'dictionary',
+    list: 'list',
+}
+
+
+def discover_nodes(node_folder: str) -> dict:
+    node_registry = dict()
+
+    folder = pathlib.Path(node_folder)
+
+    if not folder.exists():
+        raise FileNotFoundError(f'node folder {node_folder} does not exist')
+
+    for node_type_dir in folder.iterdir():
+        if not node_type_dir.is_dir():
+            continue
+
+        nodes = discover_node_marks(str(node_type_dir))
+
+        if nodes:
+            node_registry[node_type_dir.name] = nodes
+
+    return node_registry
+
+
+def discover_node_marks(node_folder: str) -> dict:
+    folder = pathlib.Path(node_folder)
+    registry = dict()
+
+    marks = folder.glob('_*')
+
+    for mark_dir in filter(lambda d: d.is_dir(), marks):
+        mark = mark_dir.name[1:]
+        config_path = mark_dir / 'config.toml'
+
+        if not config_path.exists():
+            continue
+
+        with open(config_path, 'rb') as f:
+            config = tomllib.load(f)
+            arguments = config.get('arguments', {})
+
+            registry[mark] = {
+                'arguments': {
+                    arg_name: {
+                        'default': arg_value,
+                        'type': _TYPE_MAP.get(type(arg_value)),
+                    }
+                    for arg_name, arg_value in arguments.items()
+                }
+            }
+
+    return registry
+
+
+def get_types(nodes: dict) -> list[str]:
+    return sorted(nodes.keys())
+
+
+def get_marks(nodes: dict, node_type: str) -> list[str]:
+    return sorted(nodes.get(node_type, {}).keys())
+
+
+def get_config(nodes: dict, node_type: str, node_mark: str) -> dict | None:
+    return nodes.get(node_type, {}).get(node_mark)