Metadata-Version: 2.4
Name: kawapythonserver
Version: 0.37.11
Summary: Kawa python server to run python scripts from Kawa - https://learn.kawa.ai
Author-email: Kawa Analytics <emmmanuel@kawa.ai>, Kawa Analytics <greg@kawa.ai>, Kawa Analytics <max@kawa.ai>
Maintainer-email: Kawa Analytics <max@kawa.ai>, Kawa Analytics <greg@kawa.ai>, Kawa Analytics <emmmanuel@kawa.ai>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: kywy>=0.37.10
Requires-Dist: pandas
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pex==2.95.2
Requires-Dist: cachetools==5.3.3
Requires-Dist: filelock==3.18.0
Requires-Dist: importlib_metadata==8.6.1

# Kawa Python Server 

It is the python runtime for the Kawa platform.
Please refer to this documentation to register python runtime in the Kawa platform:
[Register python runtimes](https://github.com/kawa-analytics/kywy-documentation/blob/main/notebooks/administration/01_kawa_administration_notebook.ipynb
).

## Configure the server

Create a `.env` file in the root of the venv.
It must contain the following environment variables:

```dotenv
# This is the secret for this server.
# It will need to be set on KAWA platform too 
# to communicate with this server.
# You can generate it like that: head /dev/urandom | sha256sum | cut -d ' ' -f 1
# (REQUIRED)
KAWA_AUTOMATION_SERVER_AES_KEY=8c180b7df391a24fcdf5504fadbd37f2df79ead5c4b36987acb683bd8e8bc465

# This defines the URL of the KAWA platform this python server will be paired with
# (OPTIONAL) Defaults to http://localhost:8080
KAWA_URL=http://localhost:8080

# This will define on which host/port the python server will listen
# (OPTIONAL) Defaults to 0.0.0.0, port 8815
# KAWA_AUTOMATION_SERVER_HOST=0.0.0.0
# KAWA_AUTOMATION_SERVER_PORT=8815

# This will override the path to the pex executable.
# pex is used by the script runner to package dependencies
# https://docs.pex-tool.org/
# (OPTIONAL) Defaults to pex
# KAWA_AUTOMATION_PEX_EXECUTABLE_PATH=pex

# Defines the working dir of the python server
# It will store pex files and sync files
# (OPTIONAL) Defaults to /tmp
# KAWA_AUTOMATION_SERVER_WORKING_DIRECTORY=/tmp

# If set to true, PEX will use pip config.
# This is important if some specific configuration is required (such as a private package registry etc)
# (OPTIONAL) Defaults to false
# KW_PEX_USE_PIP_CONFIG=false
```

## Starting the server

Just run `kawapythonserver`

## Health

The server answers two Flight actions.

- `health` proves that the server answers: `{"status": "OK", "version": "…"}`. The KAWA server calls it
  before each script run.
- `health_report` tells whether the server can run a script right now. The KAWA server shows the result
  in the `pythonRunner` field of its `/health` page.

`health_report` answers a status, `OK` or `KO`, and one line per check: `OK`, or a sentence that says
what is wrong.

| Check | It fails when |
|---|---|
| `kawaServer` | the KAWA server has not been reached for 30 seconds: wrong `KAWA_URL`, wrong key, network. Scripts stay pending. |
| `pollingThread` | the thread that picks up jobs is dead. |
| `workers` | none of the threads that run jobs is alive. |
| `workingDirectory` | a small file cannot be written in the working directory: missing, read-only, disk full. |
| `pex` | the `pex` executable is not found. |
| `scriptRunner` | the `script_runner.py` file is not found. |

It also gives, for information: the versions (server, kywy, Python), the URL of the KAWA server, the
number of worker threads alive, and the free space of the working directory's disk.

No script is run and the KAWA server is not called: the polling thread already asks it every second.

## Version

The Flight action `version` tells what the server was built from. The KAWA server and the workflow
engine answer the same five fields on their `GET /version`.

```json
{
  "component": "kawa-python-runner",
  "version": "0.37.11",
  "commitHash": "520bc14",
  "buildDate": "2026-11-11 22:21:40",
  "pipelineId": "2145778812"
}
```

`version` is the package version, from `pyproject.toml`. The commit, the date (UTC) and the GitLab CI
pipeline are stamped into the package when it is built: `python stamp_build_info.py` writes
`src/kawapythonserver/_build_info.py`, which git ignores and the package carries. The CI runs it before
`python -m build`, and so does `build_and_publish.sh`.

A checkout that was never built says `dev` for these three. A build outside the CI says `dev` for the
pipeline.



