Metadata-Version: 2.4
Name: kodosumi
Version: 0.8.3
Summary: kodosumi framework to execute and orchestrate agentic services safe and at scale
Author-email: Michael Rau <m.rau@house-of-communication.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.masumi.network/
Project-URL: Repository, https://github.com/masumi-network/kodosumi
Project-URL: Issues, https://github.com/masumi-network/kodosumi/issues
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click
Requires-Dist: pydantic[email]
Requires-Dist: pydantic_settings
Requires-Dist: ray[serve]
Requires-Dist: litestar
Requires-Dist: fastapi
Requires-Dist: fastapi_utils
Requires-Dist: jinja2
Requires-Dist: uvicorn
Requires-Dist: python-jose
Requires-Dist: python-multipart
Requires-Dist: multipart
Requires-Dist: aiofiles
Requires-Dist: bson
Requires-Dist: bcrypt
Requires-Dist: sqlalchemy
Requires-Dist: advanced-alchemy
Requires-Dist: aiosqlite
Requires-Dist: bs4
Requires-Dist: ansi2html
Requires-Dist: pyyaml
Requires-Dist: markdown
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-asyncio; extra == "tests"
Requires-Dist: pytest-httpserver; extra == "tests"
Requires-Dist: isort; extra == "tests"
Requires-Dist: autopep8; extra == "tests"
Requires-Dist: debugpy; extra == "tests"
Requires-Dist: pytest_httpserver; extra == "tests"
Requires-Dist: toml; extra == "tests"
Requires-Dist: twine; extra == "tests"
Dynamic: license-file

# >kodosumi

> [!NOTE]
>
> This is an early development version of kodosumi. The documentation is under development, too. See the [key concepts](docs/concepts.md).

kodosumi is a runtime environment to manage and execute agentic services at scale. The system is based on [ray](https://ray.io) - a distributed computing framework - and a combination of [litestar](https://litestar.dev/) and [fastapi](https://fastapi.tiangolo.com/) to deliver men/machine interaction.

kodosumi is one component of a larger ecosystem with [masumi and sokosumi](https://www.masumi.network/).


# introduction

kodosumi consists of three main building blocks:

1. The Ray cluster to execute agentic services at scale.
2. The kodosumi web interface and API services.
3. Agentic Services delivered through kodosumi and executed through Ray.


# installation

This installation has been tested with versions `ray==2.44.1` and `python==3.12.6`.

### STEP 1 - clone and install kodosumi.

```bash
pip install kodosumi
```

### STEP 2 - start ray as a daemon.

```bash
ray start --head
```

Check ray status with `ray status` and visit ray dashboard at [http://localhost:8265](http://localhost:8265). For more information about ray visit [ray's documentation](https://docs.ray.io/en/latest).


### STEP 3 - prepare environment

To use [openai](https://openai.com/) API you need to create a local file `.env` to define the following API keys:

```
OPENAI_API_KEY=...
EXA_API_KEY=...
SERPER_API_KEY=...
```


### STEP 4 - deploy example apps with `ray serve`

Deploy the example services available in folder `./apps`. Use file `apps/config.yaml`.

```bash
serve deploy apps/config.yaml
```

Please be patient if the Ray serve applications take a while to setup, install and deploy. Follow the deployment process with the Ray dashboard at [http://localhost:8265/#/serve](http://localhost:8265/#/serve). On my laptop initial deployment takes three to four minutes.


### STEP 5 - start kodosumi

Finally start the kodosumi components and register ray endpoints available at 
[http://localhost:8001/-/routes](http://localhost:8001/-/routes).


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


### STEP 6 - Look around

Visit kodosumi admin panel at [http://localhost:3370](http://localhost:3370). The default user is defined in `config.py` and reads `name=admin` and `password=admin`. If one or more Ray serve applications are not yet available when kodosumi starts, you need to refresh the list of registered flows. Visit **Routes Screen** at [(http://localhost:3370/admin/routes](http://localhost:3370/admin/routes) in the **Admin Panel** at [http://localhost:3370/admin/flow](http://localhost:3370/admin/flow). See also the **OpenAPI documents with Swagger** [http://localhost:3370/schema/swagger](http://localhost:3370/schema/swagger). 

If all went well, then you see a couple of test services. Be aware you need some OpenAPI, Exa and Serper API keys if you want to use all Agentic Services.

Stop the kodosumi services and spooler by hitting `CNTRL+C` in the corresponding terminal. Stop Ray _serve_ with `serve shutdown --yes`. Stop the ray daemon with command `ray stop`.


# development notes

The development notes provide an overview for various flavours on how to run and deploy agentic services.

Follow the examples:

* [Function Blueprint](apps/example7/service.py)
* [Search for Armstrong Numbers](apps/example1.py) and with [nested remote calls](apps/example2.py)
* [Crew of Agents to craft a Hymn using OpenAI](apps/example3.py)
* [Crew of Agents to craft a Marketing Campaign using OpenAI](apps/example4/service.py)
* [Crew of Agents to craft a Job Posting using OpenAI](apps/example4/service.py)
