avtomatika 1.0b3__tar.gz → 1.0b4__tar.gz

{avtomatika-1.0b3/src/avtomatika.egg-info → avtomatika-1.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avtomatika
-Version: 1.0b3
+Version: 1.0b4
 Summary: A state-machine based orchestrator for long-running AI and other jobs.
 Project-URL: Homepage, https://github.com/avtomatika-ai/avtomatika
 Project-URL: Bug Tracker, https://github.com/avtomatika-ai/avtomatika/issues
@@ -334,6 +334,24 @@ The orchestrator's behavior can be configured through environment variables. Add
 
 **Important:** The system employs **strict validation** for configuration files (`clients.toml`, `workers.toml`) at startup. If a configuration file is invalid (e.g., malformed TOML, missing required fields), the application will **fail fast** and exit with an error, rather than starting in a partially broken state. This ensures the security and integrity of the deployment.
 
+### Configuration Files
+
+To manage access and worker settings securely, Avtomatika uses TOML configuration files.
+
+-   **`clients.toml`**: Defines API clients, their tokens, plans, and quotas.
+    ```toml
+    [client_premium]
+    token = "secret-token-123"
+    plan = "premium"
+    ```
+-   **`workers.toml`**: Defines individual tokens for workers to enhance security.
+    ```toml
+    [gpu-worker-01]
+    token = "worker-secret-456"
+    ```
+
+For detailed specifications and examples, please refer to the [**Configuration Guide**](docs/configuration.md).
+
 ### Fault Tolerance
 
 The orchestrator has built-in mechanisms for handling failures based on the `error.code` field in a worker's response.
@@ -418,11 +436,21 @@ To run the `avtomatika` test suite:
 pytest avtomatika/tests/
 ```
 
+### Interactive API Documentation
+
+Avtomatika provides a built-in interactive API documentation page (similar to Swagger UI) that is automatically generated based on your registered blueprints.
+
+*   **Endpoint:** `/_public/docs`
+*   **Features:**
+    *   **List of all system endpoints:** Detailed documentation for Public, Protected, and Worker API groups.
+    *   **Dynamic Blueprint Documentation:** Automatically generates and lists documentation for all blueprints registered in the engine, including their specific API endpoints.
+    *   **Interactive Testing:** Allows you to test API calls directly from the browser. You can provide authentication tokens, parameters, and request bodies to see real server responses.
+
 ## Detailed Documentation
 
-For a deeper dive into the system, please refer to the following documents in the `docs/` directory:
+For a deeper dive into the system, please refer to the following documents:
 
-- [**Architecture Guide**](docs/architecture.md): A detailed overview of the system components and their interactions.
-- [**API Reference**](docs/api_reference.md): Full specification of the HTTP API.
-- [**Deployment Guide**](docs/deployment.md): Instructions for deploying with Gunicorn/Uvicorn and NGINX.
-- [**Cookbook**](docs/cookbook/README.md): Examples and best practices for creating blueprints.
+- [**Architecture Guide**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/architecture.md): A detailed overview of the system components and their interactions.
+- [**API Reference**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/api_reference.md): Full specification of the HTTP API.
+- [**Deployment Guide**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/deployment.md): Instructions for deploying with Gunicorn/Uvicorn and NGINX.
+- [**Cookbook**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/cookbook/README.md): Examples and best practices for creating blueprints.

{avtomatika-1.0b3 → avtomatika-1.0b4}/README.md

@@ -288,6 +288,24 @@ The orchestrator's behavior can be configured through environment variables. Add
 
 **Important:** The system employs **strict validation** for configuration files (`clients.toml`, `workers.toml`) at startup. If a configuration file is invalid (e.g., malformed TOML, missing required fields), the application will **fail fast** and exit with an error, rather than starting in a partially broken state. This ensures the security and integrity of the deployment.
 
+### Configuration Files
+
+To manage access and worker settings securely, Avtomatika uses TOML configuration files.
+
+-   **`clients.toml`**: Defines API clients, their tokens, plans, and quotas.
+    ```toml
+    [client_premium]
+    token = "secret-token-123"
+    plan = "premium"
+    ```
+-   **`workers.toml`**: Defines individual tokens for workers to enhance security.
+    ```toml
+    [gpu-worker-01]
+    token = "worker-secret-456"
+    ```
+
+For detailed specifications and examples, please refer to the [**Configuration Guide**](docs/configuration.md).
+
 ### Fault Tolerance
 
 The orchestrator has built-in mechanisms for handling failures based on the `error.code` field in a worker's response.
@@ -372,11 +390,21 @@ To run the `avtomatika` test suite:
 pytest avtomatika/tests/
 ```
 
+### Interactive API Documentation
+
+Avtomatika provides a built-in interactive API documentation page (similar to Swagger UI) that is automatically generated based on your registered blueprints.
+
+*   **Endpoint:** `/_public/docs`
+*   **Features:**
+    *   **List of all system endpoints:** Detailed documentation for Public, Protected, and Worker API groups.
+    *   **Dynamic Blueprint Documentation:** Automatically generates and lists documentation for all blueprints registered in the engine, including their specific API endpoints.
+    *   **Interactive Testing:** Allows you to test API calls directly from the browser. You can provide authentication tokens, parameters, and request bodies to see real server responses.
+
 ## Detailed Documentation
 
-For a deeper dive into the system, please refer to the following documents in the `docs/` directory:
+For a deeper dive into the system, please refer to the following documents:
 
-- [**Architecture Guide**](docs/architecture.md): A detailed overview of the system components and their interactions.
-- [**API Reference**](docs/api_reference.md): Full specification of the HTTP API.
-- [**Deployment Guide**](docs/deployment.md): Instructions for deploying with Gunicorn/Uvicorn and NGINX.
-- [**Cookbook**](docs/cookbook/README.md): Examples and best practices for creating blueprints.
+- [**Architecture Guide**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/architecture.md): A detailed overview of the system components and their interactions.
+- [**API Reference**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/api_reference.md): Full specification of the HTTP API.
+- [**Deployment Guide**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/deployment.md): Instructions for deploying with Gunicorn/Uvicorn and NGINX.
+- [**Cookbook**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/cookbook/README.md): Examples and best practices for creating blueprints.

{avtomatika-1.0b3 → avtomatika-1.0b4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "avtomatika"
-version = "1.0b3"
+version = "1.0b4"
 description = "A state-machine based orchestrator for long-running AI and other jobs."
 readme = "README.md"
 requires-python = ">=3.11"

{avtomatika-1.0b3 → avtomatika-1.0b4}/src/avtomatika/api.html

@@ -199,17 +199,6 @@
                             { code: '202 Accepted', description: 'Job successfully accepted for processing.', body: { "status": "accepted", "job_id": "..." } }
                         ]
                     },
-                    {
-                        id: 'post-create-showcase-job',
-                        name: 'Create a Full Showcase Job',
-                        method: 'POST',
-                        path: '/api/v1/jobs/full_showcase',
-                        description: 'Creates and starts a new instance (Job) of the `full_showcase` blueprint. This blueprint demonstrates most of the features of the Avtomatika library.',
-                        request: { body: { "path": "/path/to/video.mp4", "user_id": "user-123", "quality": "high" } },
-                        responses: [
-                            { code: '202 Accepted', description: 'Job successfully accepted for processing.', body: { "status": "accepted", "job_id": "..." } }
-                        ]
-                    },
                     {
                         id: 'get-job-status',
                         name: 'Get Job Status',

{avtomatika-1.0b3 → avtomatika-1.0b4}/src/avtomatika/engine.py

@@ -599,17 +599,53 @@ class OrchestratorEngine:
         await load_client_configs_to_redis(self.storage)
         return web.json_response({"status": "db_flushed"}, status=200)
 
-    @staticmethod
-    async def _docs_handler(request: web.Request) -> web.Response:
+    async def _docs_handler(self, request: web.Request) -> web.Response:
+        import json
         from importlib import resources
 
         try:
             content = resources.read_text("avtomatika", "api.html")
-            return web.Response(text=content, content_type="text/html")
         except FileNotFoundError:
             logger.error("api.html not found within the avtomatika package.")
             return web.json_response({"error": "Documentation file not found on server."}, status=500)
 
+        # Generate dynamic documentation for registered blueprints
+        blueprint_endpoints = []
+        for bp in self.blueprints.values():
+            if not bp.api_endpoint:
+                continue
+
+            version_prefix = f"/{bp.api_version}" if bp.api_version else ""
+            endpoint_path = bp.api_endpoint if bp.api_endpoint.startswith("/") else f"/{bp.api_endpoint}"
+            full_path = f"/api{version_prefix}{endpoint_path}"
+
+            blueprint_endpoints.append(
+                {
+                    "id": f"post-create-{bp.name.replace('_', '-')}",
+                    "name": f"Create {bp.name.replace('_', ' ').title()} Job",
+                    "method": "POST",
+                    "path": full_path,
+                    "description": f"Creates and starts a new instance (Job) of the `{bp.name}` blueprint.",
+                    "request": {"body": {"initial_data": {}}},
+                    "responses": [
+                        {
+                            "code": "202 Accepted",
+                            "description": "Job successfully accepted for processing.",
+                            "body": {"status": "accepted", "job_id": "..."},
+                        }
+                    ],
+                }
+            )
+
+        # Inject dynamic endpoints into the apiData structure in the HTML
+        if blueprint_endpoints:
+            endpoints_json = json.dumps(blueprint_endpoints, indent=2)
+            # We insert the new endpoints at the beginning of the 'Protected API' group
+            marker = "group: 'Protected API',\n                endpoints: ["
+            content = content.replace(marker, f"{marker}\n{endpoints_json.strip('[]')},")
+
+        return web.Response(text=content, content_type="text/html")
+
     def _setup_routes(self):
         public_app = web.Application()
         public_app.router.add_get("/status", status_handler)

{avtomatika-1.0b3 → avtomatika-1.0b4/src/avtomatika.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avtomatika
-Version: 1.0b3
+Version: 1.0b4
 Summary: A state-machine based orchestrator for long-running AI and other jobs.
 Project-URL: Homepage, https://github.com/avtomatika-ai/avtomatika
 Project-URL: Bug Tracker, https://github.com/avtomatika-ai/avtomatika/issues
@@ -334,6 +334,24 @@ The orchestrator's behavior can be configured through environment variables. Add
 
 **Important:** The system employs **strict validation** for configuration files (`clients.toml`, `workers.toml`) at startup. If a configuration file is invalid (e.g., malformed TOML, missing required fields), the application will **fail fast** and exit with an error, rather than starting in a partially broken state. This ensures the security and integrity of the deployment.
 
+### Configuration Files
+
+To manage access and worker settings securely, Avtomatika uses TOML configuration files.
+
+-   **`clients.toml`**: Defines API clients, their tokens, plans, and quotas.
+    ```toml
+    [client_premium]
+    token = "secret-token-123"
+    plan = "premium"
+    ```
+-   **`workers.toml`**: Defines individual tokens for workers to enhance security.
+    ```toml
+    [gpu-worker-01]
+    token = "worker-secret-456"
+    ```
+
+For detailed specifications and examples, please refer to the [**Configuration Guide**](docs/configuration.md).
+
 ### Fault Tolerance
 
 The orchestrator has built-in mechanisms for handling failures based on the `error.code` field in a worker's response.
@@ -418,11 +436,21 @@ To run the `avtomatika` test suite:
 pytest avtomatika/tests/
 ```
 
+### Interactive API Documentation
+
+Avtomatika provides a built-in interactive API documentation page (similar to Swagger UI) that is automatically generated based on your registered blueprints.
+
+*   **Endpoint:** `/_public/docs`
+*   **Features:**
+    *   **List of all system endpoints:** Detailed documentation for Public, Protected, and Worker API groups.
+    *   **Dynamic Blueprint Documentation:** Automatically generates and lists documentation for all blueprints registered in the engine, including their specific API endpoints.
+    *   **Interactive Testing:** Allows you to test API calls directly from the browser. You can provide authentication tokens, parameters, and request bodies to see real server responses.
+
 ## Detailed Documentation
 
-For a deeper dive into the system, please refer to the following documents in the `docs/` directory:
+For a deeper dive into the system, please refer to the following documents:
 
-- [**Architecture Guide**](docs/architecture.md): A detailed overview of the system components and their interactions.
-- [**API Reference**](docs/api_reference.md): Full specification of the HTTP API.
-- [**Deployment Guide**](docs/deployment.md): Instructions for deploying with Gunicorn/Uvicorn and NGINX.
-- [**Cookbook**](docs/cookbook/README.md): Examples and best practices for creating blueprints.
+- [**Architecture Guide**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/architecture.md): A detailed overview of the system components and their interactions.
+- [**API Reference**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/api_reference.md): Full specification of the HTTP API.
+- [**Deployment Guide**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/deployment.md): Instructions for deploying with Gunicorn/Uvicorn and NGINX.
+- [**Cookbook**](https://github.com/avtomatika-ai/avtomatika/blob/main/docs/cookbook/README.md): Examples and best practices for creating blueprints.

{avtomatika-1.0b3 → avtomatika-1.0b4}/tests/test_engine.py

@@ -592,6 +592,28 @@ async def test_get_jobs_invalid_params(engine):
     assert response.status == 400
 
 
+@pytest.mark.asyncio
+async def test_docs_handler_injection(engine):
+    from src.avtomatika.blueprint import StateMachineBlueprint
+
+    bp = StateMachineBlueprint(name="test_bp", api_endpoint="/jobs/test", api_version="v1")
+
+    @bp.handler_for("start", is_start=True)
+    async def start(context, actions):
+        pass
+
+    engine.register_blueprint(bp)
+
+    # Mock request
+    request = MagicMock()
+
+    response = await engine._docs_handler(request)
+    assert response.status == 200
+    text = response.text
+    assert "Create Test Bp Job" in text
+    assert "/api/v1/jobs/test" in text
+
+
 @pytest.mark.asyncio
 async def test_docs_handler_not_found(engine):
     with patch("importlib.resources.read_text", side_effect=FileNotFoundError):