### Clone and Install Kodosumi Examples

Source: https://docs.kodosumi.io/installation

This snippet shows how to clone the kodosumi-examples repository and install it within a Python virtual environment. This process automatically installs kodosumi and Ray as dependencies, along with any additional frameworks required by the examples.

```bash
git clone https://github.com/masumi-network/kodosumi-examples.git
cd ./kodosumi-examples
pip install .
```

--------------------------------

### Run Kodosumi Example with Uvicorn

Source: https://docs.kodosumi.io/installation

This snippet demonstrates how to run a kodosumi example service, specifically the 'hymn' example, as a standalone application using `uvicorn`. This starts an ASGI server on port 8011, making the service's HTTP endpoints accessible. It's a recommended practice for debugging.

```bash
uvicorn kodosumi_examples.hymn.app:app --port 8011
```

--------------------------------

### Start Kodosumi documentation development server

Source: https://docs.kodosumi.io/make

Navigates to the 'docs' directory and starts a local development server for the Kodosumi documentation. This command requires the Mintlify CLI to be installed. The documentation will be accessible at http://localhost:3000.

```bash
cd docs

mintlify dev
```

--------------------------------

### Set Up OpenAI API Key

Source: https://docs.kodosumi.io/installation

This step involves creating a `.env` file to store your OpenAI API key. This key is necessary for running specific examples within the kodosumi framework that utilize OpenAI services.

```bash
# ./env
OPENAI_API_KEY=your-api-key-here
```

--------------------------------

### Bash: Install Python Dependencies

Source: https://docs.kodosumi.io/upload-example

Installs the necessary Python packages for the Kodosumi example. This includes installing the example package itself using `pip install -e .` and any additional dependencies required for specific examples, such as `python-pptx` for PowerPoint processing.

```bash
# Install the example package
pip install -e .

# Install additional dependencies for the upload example
pip install python-pptx  # For PowerPoint file processing
```

--------------------------------

### Start Ray Head Node

Source: https://docs.kodosumi.io/installation

This command initiates the Ray head node on your local machine, loading environment variables from the `.env` file using `dotenv`. It's essential for distributed task execution within kodosumi examples. Check the status via `ray status` and access the dashboard at `http://localhost:8265`.

```bash
dotenv run -- ray start --head
```

--------------------------------

### Setup Python Virtual Environment and Install Kodosumi

Source: https://docs.kodosumi.io/deploy

Creates a Python virtual environment and installs Kodosumi from PyPI or a development branch. Ensure your Python executable path is correct.

```bash
mkdir ~/kodosumi
cd kodosumi
python -m venv .venv
source .venv/bin/activate
pip install kodosumi
# or for development version:
pip install "kodosumi @ git+https://github.com/masumi-network/kodosumi.git@dev"
```

--------------------------------

### Register Multiple Services with Kodosumi Panel

Source: https://docs.kodosumi.io/installation

This command shows how to register multiple kodosumi example services simultaneously with the kodosumi panel by providing multiple `--register` flags. This is useful when running several services that need to be managed centrally.

```bash
koco start --register http://localhost:8011/openapi.json --register http://localhost:8012/openapi.json
```

--------------------------------

### Start koco with Ray Serve Endpoint

Source: https://docs.kodosumi.io/installation

Initializes the koco service, registering it with the Ray Serve endpoint. This is necessary when using Ray Serve to ensure koco can communicate with the deployed services. The URL points to the Ray Serve proxy.

```bash
koco start --register http://localhost:8000/-/routes

```

--------------------------------

### POST /serve - Start or Reconcile Ray Serve

Source: https://docs.kodosumi.io/deploy

Initiates the deployment process for all services marked as 'to-deploy' or reconciles the current state of Ray Serve.

```APIDOC
## POST /serve

### Description
Requests Ray Serve to enter its desired state. This command will trigger the deployment of any services that are currently in the 'to-deploy' state.

### Method
POST

### Endpoint
/serve

### Parameters
#### Query Parameters
- **timeout** (integer) - Optional - The maximum time in seconds to wait for Ray Serve to reach the desired state. Defaults to a reasonable timeout if not provided.

### Request Example
None (request body is typically empty)

### Response
#### Success Response (201)
Indicates that Ray Serve has successfully started or reconciled its state.

#### Error Response (500)
- **message** (string) - Indicates an internal server error occurred during the process.
```

--------------------------------

### Start koco with Ray Serve Endpoint (Multi-Service)

Source: https://docs.kodosumi.io/installation

Starts the koco service and registers it with the Ray Serve endpoint defined in the multi-service configuration. This command uses the port specified in the `config.yaml` file.

```bash
koco start --register http://localhost:8001/-/routes

```

--------------------------------

### Run a Single Service with Ray Serve

Source: https://docs.kodosumi.io/installation

Starts a Ray Serve application for development and testing. This command is used to run a single service locally, similar to using uvicorn but with Ray Serve's framework. It requires specifying the application object.

```bash
serve run kodosumi_examples.hymn.app:fast_app

```

--------------------------------

### Start Kodosumi Panel and Register Deployments

Source: https://docs.kodosumi.io/deploy

Launches the Kodosumi admin panel and registers Ray deployments. This step is crucial for managing services at runtime.

```bash
koco serve --register http://localhost:8001/-/routes
```

--------------------------------

### Start and Verify Ray Head Node

Source: https://docs.kodosumi.io/upload-example

Commands to start the Ray head node and check its status. Ray is a distributed computing framework, and these commands initiate and confirm the core component for distributed execution.

```bash
# Start Ray head node
ray start --head

# Verify Ray is running
ray status
```

--------------------------------

### Kodosumi Panel API: Login Example (Python)

Source: https://docs.kodosumi.io/deploy

Demonstrates how to authenticate with the Kodosumi panel API using httpx. This is the first step to interact with the deployment API for managing Ray Serve deployments.

```python
import httpx
from pprint import pprint

# login
resp = httpx.get("http://localhost:3370/login?name=admin&password=admin")
cookies = resp.cookies
```

--------------------------------

### Register Service with Kodosumi Panel

Source: https://docs.kodosumi.io/installation

After launching an example service with uvicorn, this command registers its OpenAPI specification URL with the kodosumi panel. This allows the kodosumi admin panel to discover and manage the service. Visit the admin panel at `http://localhost:3370`.

```bash
koco start --register http://localhost:8011/openapi.json
```

--------------------------------

### Start Kodosumi Services

Source: https://docs.kodosumi.io/upload-example

Commands to start essential Kodosumi services: the spooler daemon and the panel web interface. These services manage job scheduling and provide a user interface for interacting with the deployed application.

```bash
# Start the spooler daemon
koco spool

# Start the panel web interface
koco serve --register http://localhost:8001/-/routes
```

--------------------------------

### GET /deploy - Retrieve All Deployments

Source: https://docs.kodosumi.io/deploy

Retrieves a list of all currently active Ray Serve deployments.

```APIDOC
## GET /deploy

### Description
Retrieves a dictionary of all active deployments. The keys are the deployment names and the values indicate their deployment status.

### Method
GET

### Endpoint
/deploy

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **deployments** (object) - A dictionary where keys are deployment names (string) and values are their status (string, e.g., 'RUNNING', 'UNHEALTHY', 'to-deploy').

#### Response Example
```json
{
  "prime": "to-deploy"
}
```
```

--------------------------------

### Bash: Clone Kodosumi Examples Repository

Source: https://docs.kodosumi.io/upload-example

Clones the `kodosumi-examples` repository from GitHub to the local machine. This is the first step in setting up the environment to run the file processing example.

```bash
git clone https://github.com/masumi-network/kodosumi-examples.git
cd kodosumi-examples
```

--------------------------------

### Ray Serve Service Configuration (hymn.yaml)

Source: https://docs.kodosumi.io/installation

Configures a specific service deployment within a Ray Serve multi-service setup. It specifies the service name, route prefix, import path for the application, and runtime environment including dependencies and environment variables.

```yaml
name: hymn
route_prefix: /hymn
import_path: kodosumi_examples.hymn.app:fast_app
runtime_env:
  pip:
    - crewai
    - crewai_tools
  env_vars:
    OTEL_SDK_DISABLED: "true"
    OPENAI_API_KEY: "your-api-key-here"

```

--------------------------------

### Setup Imports for Kodosumi Upload App

Source: https://docs.kodosumi.io/upload-example

Imports necessary libraries for the Kodosumi Upload App, including asyncio, os, re, time, pathlib, tempfile, traceback, fastapi, uvicorn, pptx, and core Kodosumi components like ServeAPI, forms, Tracer, and Launch. It also initializes the ServeAPI application.

```python
import asyncio, os, re, time
from pathlib import Path
from tempfile import mkdtemp
from traceback import format_exc

import fastapi
import uvicorn
from pptx import Presentation
from ray import remote, serve

from kodosumi.core import ServeAPI, forms as F, Tracer, Launch
from kodosumi.response import Markdown

app = ServeAPI()
```

--------------------------------

### Install Mintlify CLI globally with npm

Source: https://docs.kodosumi.io/make

Installs the Mintlify command-line interface globally using npm. Ensure Node.js and npm are installed and in your PATH. This command makes the 'mintlify' command available system-wide.

```bash
npm install -g mintlify
```

--------------------------------

### Build Kodosumi documentation for production with Mintlify

Source: https://docs.kodosumi.io/make

Navigates to the 'docs' directory and builds the Kodosumi documentation for production deployment using the Mintlify CLI. The output will be generated in the .mintlify directory. This command requires the Mintlify CLI to be installed.

```bash
cd docs

mintlify build
```

--------------------------------

### Ray Serve Service Configuration (prime.yaml)

Source: https://docs.kodosumi.io/installation

Configures the 'prime' service deployment for Ray Serve. This file specifies the service name, its route prefix, and the import path for the application object.

```yaml
name: prime
route_prefix: /prime
import_path: kodosumi_examples.prime.app:fast_app

```

--------------------------------

### Run koco Deployment with Ray Serve Configuration

Source: https://docs.kodosumi.io/installation

Deploys the services configured in the specified YAML files using Ray Serve. This command initiates the deployment process to the Ray cluster based on the provided configuration.

```bash
koco deploy --run --file ./data/config/config.yaml

```

--------------------------------

### GET /deploy/config - Retrieve Base Configuration

Source: https://docs.kodosumi.io/deploy

Retrieves the base configuration file for Ray Serve.

```APIDOC
## GET /deploy/config

### Description
Retrieves the content of the base configuration file (`config.yaml`). This configuration is used to initialize Ray Serve.

### Method
GET

### Endpoint
/deploy/config

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **content** (string) - The YAML content of the base configuration file.

#### Response Example
```yaml
proxy_location: EveryNode

http_options:
  host: 127.0.0.1
  port: 8001

grpc_options:
  port: 9001
  grpc_servicer_functions: []

logging_config:
  encoding: TEXT
  log_level: DEBUG
  logs_dir: null
  enable_access_log: true
```

#### Error Response (404)
- **message** (string) - Indicates that the base configuration file was not found.
```

--------------------------------

### koco serve

Source: https://docs.kodosumi.io/cli

Starts the Kodosumi panel API and application.

```APIDOC
## koco serve

### Description
Starts the Kodosumi panel API and application server.

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Query Parameters
- `--address` (TEXT) - Optional - App server URL (e.g., `0.0.0.0:8000`)
- `--log-file` (TEXT) - Optional - App server log file path
- `--log-file-level` (ENUM) - Optional - App server log file level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)
- `--level` (ENUM) - Optional - Screen log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)
- `--uvicorn-level` (ENUM) - Optional - Uvicorn log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)
- `--exec-dir` (TEXT) - Optional - Execution directory
- `--reload` - Optional - Reload app server on file changes
- `--register` (TEXT) - Optional - Register endpoints (can be used multiple times)

### Request Example
```bash
# Start server
koco serve

# Start server with reload and custom address
koco serve --reload --address 0.0.0.0:8000

# Start server with flow registration
koco serve --register flow1 --register flow2
```

### Response
N/A (CLI Output)
```

--------------------------------

### Deploy a Single Service to Ray Cluster

Source: https://docs.kodosumi.io/installation

Deploys a single Ray Serve application to a Ray cluster. This command is typically used for production environments, sending an asynchronous deployment request to the cluster.

```bash
serve deploy kodosumi_examples.hymn.app:fast_app

```

--------------------------------

### POST /deploy/config - Create Base Configuration

Source: https://docs.kodosumi.io/deploy

Creates or updates the base configuration file for Ray Serve.

```APIDOC
## POST /deploy/config

### Description
Creates or updates the base configuration file for Ray Serve. This endpoint is used when the base configuration does not exist.

### Method
POST

### Endpoint
/deploy/config

### Parameters
#### Request Body
- **content** (string) - Required - The YAML content for the base configuration file.

### Request Example
```yaml
proxy_location: EveryNode

http_options:
  host: 127.0.0.1
  port: 8001

grpc_options:
  port: 9001
  grpc_servicer_functions: []

logging_config:
  encoding: TEXT
  log_level: DEBUG
  logs_dir: null
  enable_access_log: true
```

### Response
#### Success Response (201)
Indicates that the configuration was successfully created or updated.

#### Error Response (400)
- **message** (string) - Indicates an invalid configuration format.
```

--------------------------------

### Verify Ray Serve Deployment State and Configuration

Source: https://docs.kodosumi.io/deploy

Checks the state of Ray Serve deployments and its base configuration. It verifies that there are no active deployments by checking if GET /deploy returns an empty JSON object and then retrieves the base configuration using GET /deploy/config.

```python
# verify no deployments
resp = httpx.get("http://localhost:3370/deploy", cookies=cookies)
assert resp.json() == {}
# verify base configuration
resp = httpx.get("http://localhost:3370/deploy/config", cookies=cookies)
print(resp.content.decode())
```

--------------------------------

### Start Kodosumi API and Application Server

Source: https://docs.kodosumi.io/cli

Starts the Kodosumi panel API and application server. Options include specifying the server address, log file paths and levels, execution directory, and enabling hot-reloading.

```bash
# Start server
koco serve

# Start server with reload and custom address
koco serve --reload --address 0.0.0.0:8000

# Start server with flow registration
koco serve --register flow1 --register flow2
```

--------------------------------

### Start Ray Cluster and Kodosumi Spooler

Source: https://docs.kodosumi.io/deploy

Initiates a Ray cluster and starts the Kodosumi spooler daemon. The spooler manages Ray Serve configuration files.

```bash
ray start --head
koco spool
koco spool --status
koco spool --stop
```

--------------------------------

### koco start

Source: https://docs.kodosumi.io/cli

Starts both the spooler and app server in a single execution.

```APIDOC
## koco start

### Description
Starts both the spooler and the app server simultaneously.

### Method
N/A (CLI Command)

### Endpoint
N/A (CLI Command)

### Parameters
#### Query Parameters
- `--exec-dir` (TEXT) - Optional - Execution directory
- `--register` (TEXT) - Optional - Register endpoints (can be used multiple times)

### Request Example
```bash
# Start complete service
koco start

# With custom execution directory
koco start --exec-dir /path/to/flows
```

### Response
N/A (CLI Output)
```

--------------------------------

### Show koco CLI Version and Help

Source: https://docs.kodosumi.io/cli

Displays the version of the koco CLI or shows help information for all available commands. This is useful for initial setup verification and understanding command usage.

```bash
koco --version  # Shows version
koco --help     # Shows help for all commands
```

--------------------------------

### POST /deploy/{name} - Deploy a Service

Source: https://docs.kodosumi.io/deploy

Deploys a new service or updates an existing one with the provided configuration.

```APIDOC
## POST /deploy/{name}

### Description
Deploys a new service to Ray Serve or updates an existing deployment. The service configuration is provided in the request body.

### Method
POST

### Endpoint
/deploy/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the service to deploy.

#### Request Body
- **configuration** (string) - Required - The YAML configuration for the service. This includes details like `route_prefix`, `import_path`, `runtime_env`, and `deployments`.

### Request Example
```yaml
name: prime
route_prefix: /prime
import_path: kodosumi_examples.prime.app:fast_app
runtime_env: 
  py_modules: 
  - https://github.com/masumi-network/kodosumi-examples/archive/2db907d955de65bed5dde6513f6359aeb18ebff1.zip
deployments:
  - name: PrimeDistribution
    num_replicas: auto
    ray_actor_options:
      num_cpus: 0.1
```

### Response
#### Success Response (201)
Indicates that the deployment request was accepted.

#### Error Response (400)
- **message** (string) - Indicates an invalid deployment configuration.
```

--------------------------------

### Deploy Ray Application with Kodosumi CLI

Source: https://docs.kodosumi.io/upload-example

Command to deploy the Ray and service configuration using the Kodosumi CLI. This command initiates the deployment process, making the Ray Serve application accessible.

```bash
# Deploy using Kodosumi CLI
koco deploy --run --file ./data/config/config.yaml
```

--------------------------------

### Python: Ray Serve Deployment

Source: https://docs.kodosumi.io/upload-example

Sets up the application for deployment using Ray Serve. It defines a `TextProcessor` class decorated with `@serve.deployment` and `@serve.ingress(app)` to act as the entry point for Ray Serve. The `if __name__ == "__main__":` block shows how to run the application using uvicorn for local testing.

```python
@serve.deployment
@serve.ingress(app)
class TextProcessor:
    pass

fast_app = TextProcessor.bind()  # type: ignore

if __name__ == "__main__":
    uvicorn.run(
        "kodosumi_examples.upload.app:app", 
        host="0.0.0.0", 
        port=8013, 
        reload=True
    )
```

--------------------------------

### Setup Kodosumi ServeAPI Application

Source: https://docs.kodosumi.io/develop

Initializes the ServeAPI application, which provides Kodosumi-specific extensions like OpenAPI documentation, error handling, authentication, input validation, and configuration management. This instance is used to define service endpoints and metadata.

```python
from kodosumi.core import ServeAPI
app = ServeAPI()
```

--------------------------------

### Stop Ray Serve Deployments

Source: https://docs.kodosumi.io/installation

Shuts down all currently running Ray Serve deployments. This command is used to clean up the environment before re-deploying or stopping services, equivalent to `koco deploy --stop`.

```bash
serve shutdown --yes

```

--------------------------------

### Perform a Dry Run of koco Deployment

Source: https://docs.kodosumi.io/installation

Tests the multi-service deployment configuration without actually deploying it. This command validates the YAML configuration files and checks for potential issues before a live deployment.

```bash
koco deploy --dry-run --file ./data/config/config.yaml

```

--------------------------------

### Ray Serve Service Configuration (throughput.yaml)

Source: https://docs.kodosumi.io/installation

Configures the 'throughput' service deployment for Ray Serve. This configuration includes the service name, its route prefix, the import path, and specifies runtime dependencies.

```yaml
name: throughput
route_prefix: /throughput
import_path: kodosumi_examples.throughput.app:fast_app
runtime_env:
  pip:
    - lorem-text

```

--------------------------------

### Ray Serve Multi-Service Configuration (config.yaml)

Source: https://docs.kodosumi.io/installation

Defines the overarching configuration for a multi-service Ray Serve deployment. This includes proxy location, HTTP and gRPC options, and logging settings. It serves as the main configuration file for grouping multiple services.

```yaml
proxy_location: EveryNode

http_options:
  host: 127.0.0.1
  port: 8001

grpc_options:
  port: 9001
  grpc_servicer_functions: []

logging_config:
  encoding: TEXT
  log_level: DEBUG
  logs_dir: null
  enable_access_log: true

```

--------------------------------

### Kodosumi Deployment Configuration (YAML)

Source: https://docs.kodosumi.io/upload-example

YAML configuration files for deploying a Ray Serve application using Kodosumi. `upload_example.yaml` defines the application's name, route, and import path. `config.yaml` specifies proxy location, HTTP/gRPC options, and logging configuration.

```yaml
# upload_example.yaml
name: upload_example
route_prefix: /upload
import_path: kodosumi_examples.upload.app:fast_app
```

```yaml
# config.yaml
proxy_location: EveryNode

http_options:
  host: 127.0.0.1
  port: 8001

grpc_options:
  port: 9001
  grpc_servicer_functions: []

logging_config:
  encoding: TEXT
  log_level: DEBUG
  logs_dir: null
  enable_access_log: true
```

--------------------------------

### AsyncFileSystem Operations

Source: https://docs.kodosumi.io/upload-example

Demonstrates the usage of AsyncFileSystem for asynchronous file operations within the main processing function, including listing files and managing the file system connection.

```APIDOC
## AsyncFileSystem Operations

### Description
This section details the asynchronous file system operations used in the main `run` function, highlighting methods like `ls` for listing directory contents and `close` for managing the file system connection.

### Methods
- **`await tracer.fs()`**: Initializes an `AsyncFileSystem` instance.
- **`await afs.ls("in")`**: Asynchronously lists all files within the "in" directory.
- **`await afs.close()`**: Asynchronously closes the `AsyncFileSystem` connection.

### Usage Context
These methods are used within asynchronous functions (e.g., `async def run(...)`) to perform non-blocking I/O operations, enhancing application performance.

### Example Snippet
```python
async def run(inputs: dict, tracer: Tracer):
    afs = await tracer.fs()  # Initialize AsyncFileSystem
    files = await afs.ls("in")  # List files in the "in" directory
    # ... processing logic ...
    await afs.close()  # Close the connection
```
```

--------------------------------

### Create Ray Serve Ingress Deployment

Source: https://docs.kodosumi.io/develop

Sets up an ingress deployment for the Ray Serve framework. The `@serve.deployment` decorator converts the `NewsSearch` class into a Ray Serve deployment, and `@serve.ingress(app)` wraps it with a FastAPI application for HTTP request handling. The `fast_app` object is then bound and used for deployment configuration.

```python
from ray import serve

@serve.deployment
@serve.ingress(app)
class NewsSearch:
    pass

fast_app = NewsSearch.bind()
```

--------------------------------

### Wrap batch entrypoint with run_batch function (Python)

Source: https://docs.kodosumi.io/develop

This Python function `run_batch` acts as a wrapper for the `batch` function. It takes user inputs and a tracer object, formats the input texts, and then calls the asynchronous `batch` function. It is designed to be compatible with Kodosumi's launch mechanics.

```python
async def run_batch(inputs: dict, tracer: Tracer):
    texts = inputs.get("texts", [])
    start = inputs.get("start", datetime.datetime.now())
    end = inputs.get("end", datetime.datetime.now())
    return await batch(texts, start, end, tracer)
```

--------------------------------

### Verify Service Deployment State

Source: https://docs.kodosumi.io/deploy

Checks the deployment status of a specific service, 'prime'. It fetches the deployment list using GET /deploy and asserts that the response JSON contains {'prime': 'to-deploy'}, indicating the service is queued for deployment.

```python
resp = httpx.get("http://localhost:3370/deploy", cookies=cookies)
assert resp.status_code == 200
assert resp.json() == {'prime': 'to-deploy'}
```

--------------------------------

### Retrieve Ray Serve Deployment Status

Source: https://docs.kodosumi.io/deploy

Fetches the current status of all Ray Serve deployments. It sends a GET request to the /deploy endpoint and prints the JSON response. This requires an active Ray Serve instance and valid cookies.

```python
import httpx
from pprint import pprint

# Assuming 'cookies' is already defined and contains valid authentication cookies
resp = httpx.get("http://localhost:3370/deploy", cookies=cookies)
pprint(resp.json())
```

--------------------------------

### Initiate Ray Serve State Transition

Source: https://docs.kodosumi.io/deploy

Requests Ray Serve to transition to its desired deployment state. It sends a POST request to the /serve endpoint with a timeout, as this operation can take a significant amount of time. Asserts a 201 status code for a successful request.

```python
resp = httpx.post("http://localhost:3370/serve", cookies=cookies, timeout=30)
assert resp.status_code == 201
```

--------------------------------

### Create Ray Serve Base Configuration

Source: https://docs.kodosumi.io/deploy

Creates a base configuration for Ray Serve if one does not exist. It sends a POST request to /deploy/config with a YAML string defining the proxy location, HTTP/gRPC options, and logging configuration. Asserts a 201 status code for successful creation.

```python
base = """
proxy_location: EveryNode

http_options:
  host: 127.0.0.1
  port: 8001

grpc_options:
  port: 9001
  grpc_servicer_functions: []

logging_config:
  encoding: TEXT
  log_level: DEBUG
  logs_dir: null
  enable_access_log: true
"""
resp = httpx.post("http://localhost:3370/deploy/config", 
                  cookies=cookies,
                  content=base)
assert resp.status_code == 201
```

--------------------------------

### Start Kodosumi Spooler and App Server Together

Source: https://docs.kodosumi.io/cli

Initiates both the spooler and application server in a single command execution. This simplifies the startup process for the complete Kodosumi service. Supports specifying an execution directory and registering endpoints.

```bash
# Start complete service
koco start

# With custom execution directory
koco start --exec-dir /path/to/flows
```

--------------------------------

### Get Role by Name or ID

Source: https://docs.kodosumi.io/api-reference/access-management/get-role-by-name-or-id

Retrieves a role from the Kodosumi Panel API using its name or ID.

```APIDOC
## GET /role/{name}

### Description
Get a role by name or ID.

### Method
GET

### Endpoint
/role/{name}

#### Path Parameters
- **name** (string) - Required - The name or ID of the role to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the role.
- **name** (string) - The name of the role.
- **email** (string) - The email associated with the role.
- **active** (boolean) - Indicates if the role is active.

#### Response Example
```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "admin",
  "email": "admin@example.com",
  "active": true
}
```

#### Error Response (400)
- **status_code** (integer) - The HTTP status code.
- **detail** (string) - A message describing the error.
- **extra** (object or null) - Additional error details.

#### Error Response Example
```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```
```

--------------------------------

### GET /lock/{fid}/{lid}

Source: https://docs.kodosumi.io/api-reference/lock-control/retrieve-lock

Retrieve lock input schema. This endpoint allows you to get the input schema for a specific lock.

```APIDOC
## GET /lock/{fid}/{lid}

### Description
Get lock input schema.

### Method
GET

### Endpoint
/lock/{fid}/{lid}

### Parameters
#### Path Parameters
- **fid** (string) - Required - The ID of the facility.
- **lid** (string) - Required - The ID of the lock.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- (object) - The lock input schema.

#### Response Example
```json
{
  "example": "response body"
}
```

#### Error Response (400)
- **status_code** (integer) - The status code of the error.
- **detail** (string) - A message describing the error.
- **extra** (object|array|null) - Additional error details.

#### Response Example
```json
{
  "status_code": 400,
  "detail": "Bad Request",
  "extra": {}
}
```
```

--------------------------------

### Deploy a Service to Ray Serve

Source: https://docs.kodosumi.io/deploy

Deploys a new service, named 'prime', to Ray Serve. It sends a POST request to /deploy/prime with a YAML string specifying the service name, route prefix, import path, runtime environment, and deployment details like replica count and resource allocation. Asserts a 201 status code for successful deployment.

```python
prime = """
name: prime
route_prefix: /prime
import_path: kodosumi_examples.prime.app:fast_app
runtime_env: 
  py_modules: 
  - https://github.com/masumi-network/kodosumi-examples/archive/2db907d955de65bed5dde6513f6359aeb18ebff1.zip
deployments:
  - name: PrimeDistribution
    num_replicas: auto
    ray_actor_options:
      num_cpus: 0.1
"""
resp = httpx.post("http://localhost:3370/deploy/prime", 
                  cookies=cookies,
                  content=prime)
assert resp.status_code == 201
```

--------------------------------

### Get Role by Name or ID (OpenAPI)

Source: https://docs.kodosumi.io/api-reference/access-management/get-role-by-name-or-id

This OpenAPI definition specifies the GET endpoint '/role/{name}' for retrieving a role by its name or ID. It details the request parameters, expected responses (including success and error cases), and the schema for the RoleResponse object. This serves as a contract for interacting with the API.

```yaml
openapi: 3.1.0
info:
  title: Kodosumi API
  version: 0.9.3
  description: API documentation for the Kodosumi Panel API.
servers:
  - url: /
security: []
paths:
  /role/{name}:
    get:
      tags:
        - Access Management
      summary: Get Role by Name or ID
      description: Get a role by name or ID.
      operationId: 22_get_role
      parameters:
        - name: name
          in: path
          schema:
            type: string
          required: true
          deprecated: false
      responses:
        '200':
          description: Request fulfilled, document follows
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '400':
          description: Bad request syntax or unsupported method
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                      - 'null'
                      - object
                      - array
                type: object
                required:
                  - detail
                  - status_code
                description: Validation Exception
                examples:
                  - status_code: 400
                    detail: Bad Request
                    extra: {}
      deprecated: false
components:
  schemas:
    RoleResponse:
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        active:
          type: boolean
      type: object
      required:
        - active
        - email
        - id
        - name
      title: RoleResponse
```

--------------------------------

### Python: Main Function with AsyncFileSystem

Source: https://docs.kodosumi.io/upload-example

The main `run` function orchestrates file processing. It utilizes `AsyncFileSystem` to list files in the 'in' directory, submits file processing tasks to Ray for parallel execution using `process_file.remote()`, and then aggregates the results. It closes the file system asynchronously.

```python
async def run(inputs: dict, tracer: Tracer):
    afs = await tracer.fs()  # AsyncFileSystem for main function
    files = await afs.ls("in")  # List all uploaded files in `/in` folder
    await tracer.markdown("### File Processing Started")
    
    # Display file links
    file_links = [
        f"* [{f['path']](/files/{tracer.fid}/{f['path']})" for f in files]
    await tracer.markdown("\n".join(file_links))
    
    # Parallel processing with Ray
    futures = [
        process_file.remote(
            f['path'], tracer, ignore_errors=inputs['ignore_errors'])
        for f in files
    ]
    
    await afs.close()
    results = await asyncio.gather(*futures)
    
    # Summarize results
    output = ["### File Processing Completed"]
    for r in results:
        err = r['error']
        link = f"**ERROR:** {err}" if err else f"[markdown](/files/{tracer.fid}/out/{r['target']})"
        output.append(
            f"* {r['source']} with {r['length']} text runs in {r['runtime']:.2f}s - {link}"
        )
    
    return Markdown("\n".join(output))
```

--------------------------------

### Complete HTIL Service Example - Python

Source: https://docs.kodosumi.io/locks

A comprehensive example demonstrating a full Human-in-the-Loop (HTIL) service, including entry point definition, a runner function that uses locks for approval, and corresponding lock and lease handlers. This example showcases a document review workflow. Dependencies include kodosumi core, form inputs, and error handling modules.

```python
from kodosumi.core import ServeAPI, Launch, Tracer
from kodosumi.service.inputs.forms import Model, InputText, Checkbox, Submit, Cancel, Markdown
from kodosumi.service.inputs.errors import InputsError
from fastapi import Request

app = ServeAPI()

# Entry point form
entry_form = Model(
    InputText(label="Document Name", name="doc_name", placeholder="Enter document name"),
    InputText(label="Author", name="author", placeholder="Enter author name"),
    Submit("Start Review"),
    Cancel("Cancel"),
)

@app.enter(
    "/review",
    model=entry_form,
    summary="Document Review Workflow",
    description="Review workflow with human approval steps",
)
async def start_review(inputs: dict, request: Request) -> Launch:
    return Launch(request, "document_service:review_runner", inputs=inputs)
```

--------------------------------

### Automatic Upload Completion on Flow Start

Source: https://docs.kodosumi.io/files-api

Explains that uploads are automatically completed when a flow starts, typically after a form submission. The flow ID is used as the completion ID.

```APIDOC
## Automatic Upload Completion

### Description
Upload completion is automatically triggered when a flow is started, such as after a form submission. The flow ID (`fid`) is used as the `completion_id`.

*This is a background process and does not require a direct API call from the user's perspective for completion itself, but it impacts the state of ongoing uploads.*
```

--------------------------------

### Create Basic File Upload Form with Python

Source: https://docs.kodosumi.io/forms

Demonstrates how to construct a basic form for file processing using Kodosumi's forms library in Python. This includes text inputs, file uploads, checkboxes, and submit/cancel buttons.

```python
from kodosumi.core import forms as F

model = F.Model(
    F.Markdown("# File Processing Form"),
    F.InputText(
        name="title",
        label="Document Title",
        placeholder="Enter document title",
        required=True
    ),
    F.InputFiles(
        name="files",
        label="Upload Documents",
        multiple=True,
        required=True
    ),
    F.Checkbox(
        name="process_images",
        option="Include image processing",
        value=False
    ),
    F.Submit("Process Files"),
    F.Cancel("Cancel")
)
```