flamepy 0.3.0__tar.gz → 0.6.0__tar.gz

flamepy-0.6.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: flamepy
+Version: 0.6.0
+Summary: Python SDK for Flame, a distributed system for Agentic AI
+Author-email: XFLOPS Authors <support@xflops.io>
+Project-URL: Homepage, https://xflops.io
+Project-URL: Repository, https://github.com/xflops/flame
+Project-URL: Issues, https://github.com/xflops/flame/issues
+Keywords: distributed system,agentic ai,flame,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio>=1.80
+Requires-Dist: grpcio-tools>=1.80
+Requires-Dist: protobuf>=6.31.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.35.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: pymongo>=4
+Requires-Dist: requests>=2.32
+Requires-Dist: httpx>=0.28
+Requires-Dist: cloudpickle>=3.1
+Requires-Dist: pyarrow>=18.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Flame Python SDK
+
+Python SDK for the Flame, a distributed system for Agentic AI.
+
+For the user guide, see [Flame Python SDK](../../docs/sdk/python.md). For the detailed API surface, see [API.md](docs/API.md).
+
+## Installation
+
+```bash
+pip install flamepy
+```
+
+## Quick Start
+
+```python
+import flamepy
+
+def main():
+    # Create a session with the application, e.g. Agent
+    session = flamepy.create_session("flmping")
+    
+    # Create and run a task
+    resp = session.invoke(b"task input data")
+
+    # Handle the output of task
+    print(resp)
+
+    # Close session
+    session.close()
+
+if __name__ == "__main__":
+    main()
+```
+
+## Verify A Runner Cluster
+
+After configuring `~/.flame/flame.yaml` for a running cluster with session manager, object cache, executor manager, and the `flmrun` template application, run:
+
+```bash
+python -m flamepy.runner.e2e
+```
+
+Installed wheels also provide:
+
+```bash
+flamepy-runner-e2e
+```
+
+The check packages a tiny temporary project and verifies Runner function calls, `ObjectFuture` chaining, and a stateful instance service. Use `--json` for machine-readable output and `--python-version 3.12` to verify a specific executor Python runtime.
+
+## API Reference
+
+### Session
+
+Represents a computing session with application, e.g. Agent, Tools.
+
+```python
+# Create a session
+session = flamepy.create_session("my-app")
+
+# Close a session
+session.close()
+```
+
+### Task
+
+Represents individual computing tasks within a session.
+
+```python
+from concurrent.futures import wait
+
+# Run a task synchronously (blocks until complete)
+result = session.invoke(b"input data")
+
+# Run a task asynchronously (returns Future immediately)
+future = session.run(b"input data")
+result = future.result()  # Wait for completion
+
+# Run multiple tasks in parallel
+futures = [session.run(f"input {i}".encode()) for i in range(10)]
+wait(futures)  # Wait for all tasks to complete
+results = [f.result() for f in futures]
+
+# Create a task and get task object
+task = session.create_task(b"input data")
+
+# Get task status
+task = session.get_task(task.id)
+
+# Watch task progress
+for update in session.watch_task(task.id):
+    print(f"Task state: {update.state}")
+    if update.is_completed():
+        break
+```
+
+## Error Handling
+
+The SDK provides custom exception types for different error scenarios:
+
+```python
+from flamepy import FlameError, FlameErrorCode
+
+try:
+    session = flamepy.create_session("flmping")
+except FlameError as e:
+    if e.code == FlameErrorCode.INVALID_CONFIG:
+        print("Configuration error:", e.message)
+    elif e.code == FlameErrorCode.INVALID_STATE:
+        print("State error:", e.message)
+```
+
+## Development
+
+To set up the development environment:
+
+```bash
+# Clone the repository
+git clone https://github.com/xflops/flame.git
+cd flame/sdk/python
+
+# Install in development mode
+# Note: Use --no-build-isolation if you have setuptools>=61.0 installed
+python3 -m pip install -e . --user --no-build-isolation
+
+# Or build and install the wheel
+python3 -m build --wheel --no-isolation
+python3 -m pip install dist/flamepy-0.6.0-py3-none-any.whl --user
+
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Format code
+ruff format
+
+# Type checking
+mypy flamepy/
+```
+
+### Requirements
+
+- Python >= 3.9
+- setuptools >= 61.0 (for building from source)
+
+### Troubleshooting
+
+If you encounter issues with the package name showing as "UNKNOWN":
+
+1. Make sure you have `setuptools>=61.0` installed:
+   ```bash
+   python3 -m pip install --user --upgrade "setuptools>=61.0"
+   ```
+
+2. Clean any stale build artifacts:
+   ```bash
+   rm -rf dist build src/flamepy.egg-info *.egg-info
+   ```
+
+3. Use `--no-build-isolation` flag when installing:
+   ```bash
+   python3 -m pip install . --user --no-build-isolation
+   ```

flamepy-0.6.0/README.md

@@ -0,0 +1,165 @@
+# Flame Python SDK
+
+Python SDK for the Flame, a distributed system for Agentic AI.
+
+For the user guide, see [Flame Python SDK](../../docs/sdk/python.md). For the detailed API surface, see [API.md](docs/API.md).
+
+## Installation
+
+```bash
+pip install flamepy
+```
+
+## Quick Start
+
+```python
+import flamepy
+
+def main():
+    # Create a session with the application, e.g. Agent
+    session = flamepy.create_session("flmping")
+    
+    # Create and run a task
+    resp = session.invoke(b"task input data")
+
+    # Handle the output of task
+    print(resp)
+
+    # Close session
+    session.close()
+
+if __name__ == "__main__":
+    main()
+```
+
+## Verify A Runner Cluster
+
+After configuring `~/.flame/flame.yaml` for a running cluster with session manager, object cache, executor manager, and the `flmrun` template application, run:
+
+```bash
+python -m flamepy.runner.e2e
+```
+
+Installed wheels also provide:
+
+```bash
+flamepy-runner-e2e
+```
+
+The check packages a tiny temporary project and verifies Runner function calls, `ObjectFuture` chaining, and a stateful instance service. Use `--json` for machine-readable output and `--python-version 3.12` to verify a specific executor Python runtime.
+
+## API Reference
+
+### Session
+
+Represents a computing session with application, e.g. Agent, Tools.
+
+```python
+# Create a session
+session = flamepy.create_session("my-app")
+
+# Close a session
+session.close()
+```
+
+### Task
+
+Represents individual computing tasks within a session.
+
+```python
+from concurrent.futures import wait
+
+# Run a task synchronously (blocks until complete)
+result = session.invoke(b"input data")
+
+# Run a task asynchronously (returns Future immediately)
+future = session.run(b"input data")
+result = future.result()  # Wait for completion
+
+# Run multiple tasks in parallel
+futures = [session.run(f"input {i}".encode()) for i in range(10)]
+wait(futures)  # Wait for all tasks to complete
+results = [f.result() for f in futures]
+
+# Create a task and get task object
+task = session.create_task(b"input data")
+
+# Get task status
+task = session.get_task(task.id)
+
+# Watch task progress
+for update in session.watch_task(task.id):
+    print(f"Task state: {update.state}")
+    if update.is_completed():
+        break
+```
+
+## Error Handling
+
+The SDK provides custom exception types for different error scenarios:
+
+```python
+from flamepy import FlameError, FlameErrorCode
+
+try:
+    session = flamepy.create_session("flmping")
+except FlameError as e:
+    if e.code == FlameErrorCode.INVALID_CONFIG:
+        print("Configuration error:", e.message)
+    elif e.code == FlameErrorCode.INVALID_STATE:
+        print("State error:", e.message)
+```
+
+## Development
+
+To set up the development environment:
+
+```bash
+# Clone the repository
+git clone https://github.com/xflops/flame.git
+cd flame/sdk/python
+
+# Install in development mode
+# Note: Use --no-build-isolation if you have setuptools>=61.0 installed
+python3 -m pip install -e . --user --no-build-isolation
+
+# Or build and install the wheel
+python3 -m build --wheel --no-isolation
+python3 -m pip install dist/flamepy-0.6.0-py3-none-any.whl --user
+
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Format code
+ruff format
+
+# Type checking
+mypy flamepy/
+```
+
+### Requirements
+
+- Python >= 3.9
+- setuptools >= 61.0 (for building from source)
+
+### Troubleshooting
+
+If you encounter issues with the package name showing as "UNKNOWN":
+
+1. Make sure you have `setuptools>=61.0` installed:
+   ```bash
+   python3 -m pip install --user --upgrade "setuptools>=61.0"
+   ```
+
+2. Clean any stale build artifacts:
+   ```bash
+   rm -rf dist build src/flamepy.egg-info *.egg-info
+   ```
+
+3. Use `--no-build-isolation` flag when installing:
+   ```bash
+   python3 -m pip install . --user --no-build-isolation
+   ```

{flamepy-0.3.0 → flamepy-0.6.0}/pyproject.toml

@@ -4,76 +4,89 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flamepy"
-version = "0.3.0"
-description = "Python SDK for Flame distributed engine"
+version = "0.6.0"
+description = "Python SDK for Flame, a distributed system for Agentic AI"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 license-files = ["LICENSE"]
 authors = [
   {name = "XFLOPS Authors", email = "support@xflops.io"}
 ]
-keywords = ["distributed computing", "flame", "sdk"]
+keywords = ["distributed system", "agentic ai", "flame", "sdk"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-  "grpcio>=1.50.0",
-  "grpcio-tools>=1.50.0",
-  "protobuf>=4.21.0",
+  "grpcio>=1.80",
+  "grpcio-tools>=1.80",
+  "protobuf>=6.31.0",
+  "pydantic>=2.11.0",
+  "fastapi>=0.115.0",
+  "uvicorn>=0.35.0",
+  "pyyaml>=6.0.0",
+  "pymongo>=4",
+  "requests >= 2.32",
+  "httpx >= 0.28",
+  "cloudpickle >= 3.1",
+  "pyarrow >= 18.1.0"
 ]
 
 [project.optional-dependencies]
 dev = [
   "pytest>=7.0.0",
   "pytest-asyncio>=0.21.0",
-  "black>=22.0.0",
-  "isort>=5.0.0",
+  "ruff>=0.1.0",
   "mypy>=1.0.0",
 ]
 
 [tool.setuptools.packages.find]
-where = [
-    "src"
-]
+where = ["src"]
+include = ["flamepy*"]
+exclude = ["tests*"]
 
 [project.urls]
 Homepage = "https://xflops.io"
 Repository = "https://github.com/xflops/flame"
 Issues = "https://github.com/xflops/flame/issues"
 
-[tool.black]
-line-length = 88
-target-version = ['py38']
-include = '\.pyi?$'
-extend-exclude = '''
-/(
-  # directories
-  \.eggs
-  | \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | build
-  | dist
-)/
-'''
+[project.scripts]
+flamepy-runner-e2e = "flamepy.runner.e2e:main"
+
+[tool.ruff]
+line-length = 320
+target-version = "py39"
+exclude = [
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".tox",
+    ".venv",
+    "build",
+    "dist",
+    "src/flamepy/proto",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
 
-[tool.isort]
-profile = "black"
-multi_line_output = 3
-line_length = 88
-known_first_party = ["flame"]
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["flamepy"]
 
 [tool.mypy]
-python_version = "3.8"
+python_version = "3.9"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -95,3 +108,7 @@ module = [
 ]
 ignore_missing_imports = true 
 
+[dependency-groups]
+dev = [
+    "ruff>=0.1.0",
+]

flamepy-0.6.0/src/flamepy/__init__.py

@@ -0,0 +1,152 @@
+"""
+Copyright 2025 The Flame Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# ruff: noqa: E402, I001
+# isort: skip_file
+
+# Import proto module first to ensure types_pb2 is loaded before frontend_pb2
+from flamepy import proto  # noqa: F401
+
+# Import submodules for runner, service, and util (only as submodules)
+from . import runner, service, util
+
+# Export all core classes/types at top level
+from .core import (  # Type aliases; Constants; Enums; Exception classes; Data classes; Context and utility classes; Client functions; Client classes; Service constants; Service context classes; Service base classes; Service functions
+    DEFAULT_FLAME_CACHE_ENDPOINT,
+    DEFAULT_FLAME_CONF,
+    DEFAULT_FLAME_ENDPOINT,
+    FLAME_INSTANCE_ENDPOINT,
+    Application,
+    ApplicationAttributes,
+    ApplicationContext,
+    ApplicationID,
+    ApplicationSchema,
+    ApplicationState,
+    CommonData,
+    Connection,
+    Event,
+    FlameContext,
+    FlameContextRunner,
+    FlameError,
+    FlameErrorCode,
+    FlamePackage,
+    FlameService,
+    Message,
+    ObjectRef,
+    ResourceRequirement,
+    Session,
+    SessionAttributes,
+    SessionContext,
+    SessionID,
+    SessionState,
+    Shim,
+    Task,
+    TaskContext,
+    TaskID,
+    TaskInformer,
+    TaskInput,
+    TaskOutput,
+    TaskState,
+    TaskWatcher,
+    close_session,
+    connect,
+    create_session,
+    get_application,
+    get_object,
+    get_session,
+    list_applications,
+    list_executors,
+    list_nodes,
+    list_sessions,
+    open_session,
+    put_object,
+    register_application,
+    run,
+    unregister_application,
+    update_object,
+)
+
+__version__ = "0.6.0"
+
+__all__ = [
+    # Type aliases
+    "TaskID",
+    "SessionID",
+    "ApplicationID",
+    "Message",
+    "TaskInput",
+    "TaskOutput",
+    "CommonData",
+    # Constants
+    "DEFAULT_FLAME_CONF",
+    "DEFAULT_FLAME_ENDPOINT",
+    "DEFAULT_FLAME_CACHE_ENDPOINT",
+    # Enums
+    "SessionState",
+    "TaskState",
+    "ApplicationState",
+    "FlameErrorCode",
+    "Shim",
+    # Exception classes
+    "FlameError",
+    # Data classes
+    "Event",
+    "ResourceRequirement",
+    "SessionAttributes",
+    "ApplicationSchema",
+    "ApplicationAttributes",
+    "Task",
+    "Application",
+    "FlamePackage",
+    "FlameContextRunner",
+    # Context and utility classes
+    "TaskInformer",
+    "FlameContext",
+    # Client functions
+    "connect",
+    "create_session",
+    "open_session",
+    "register_application",
+    "unregister_application",
+    "list_applications",
+    "list_executors",
+    "list_nodes",
+    "get_application",
+    "list_sessions",
+    "get_session",
+    "close_session",
+    # Client classes
+    "Connection",
+    "Session",
+    "TaskWatcher",
+    # Service constants
+    "FLAME_INSTANCE_ENDPOINT",
+    # Service context classes
+    "ApplicationContext",
+    "SessionContext",
+    "TaskContext",
+    # Service base classes
+    "FlameService",
+    # Service functions
+    "run",
+    # Cache classes
+    "ObjectRef",
+    # Cache functions
+    "get_object",
+    "put_object",
+    "update_object",
+    # Submodules
+    "runner",
+    "service",
+    "util",
+]

flamepy-0.6.0/src/flamepy/__main__.py

@@ -0,0 +1,14 @@
+"""
+Copyright 2025 The Flame Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# This makes the flamepy package executable as a module

flamepy-0.6.0/src/flamepy/cache/__init__.py

@@ -0,0 +1,30 @@
+"""
+Copyright 2025 The Flame Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from flamepy.core.cache import (
+    ObjectRef,
+    delete_objects,
+    get_object,
+    patch_object,
+    put_object,
+    update_object,
+)
+
+__all__ = [
+    "ObjectRef",
+    "delete_objects",
+    "get_object",
+    "patch_object",
+    "put_object",
+    "update_object",
+]