Metadata-Version: 2.4
Name: desireeia-server
Version: 0.0.1
Summary: OpenAI-compatible API server and web UI for the DesireeIA local LLM engine
Author: Passaro Francesco Paolo
License: Proprietary
Keywords: llm,inference,local,desireeia,openai,server
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: desireeia>=0.0.1
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: pydantic>=2.6
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: faster-whisper>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# desireeia-server

OpenAI-compatible API server and self-hosted chat web UI for the
[DesireeIA](../README.md) local LLM inference engine. The inference motor is
**always DesireeIA** — this package is a thin HTTP layer over the existing
[`desireeia`](../python/desireeia) Python wrapper and ships everything it needs.

The external project this surface mirrors (and generalizes past) is referred
to here only as **desireeialmn**; no code or documentation text is copied from
it. Convention of this repository: the words "llama" and "colibri" are not
used anywhere in code, docs or identifiers.

## Quick start

### Install from PyPI

```bash
pip install desireeia-server
```

This also installs its `desireeia` dependency (the inference engine
wrapper, with prebuilt native binaries bundled — see
[desireeia's README](../Build/Python/README.md#bundled-platforms) for the
per-OS prerequisites, e.g. the VC++ Redistributable on Windows).

### Run

Identical on Windows, Linux and macOS — `desireeia-server` is a normal
console command once installed:

```bash
desireeia-server --model path/to/model.gguf --port 8080
# open http://127.0.0.1:8080
```

Without `--model`, the server runs in router mode: it manages whatever
checkpoints it finds in the models folder (default `<data-dir>/models`,
created automatically). Drop a GGUF in there, or upload it from the UI, and
it becomes selectable without a restart.

```bash
desireeia-server --models-dir ./models
```

By default the server runs in the foreground (logs print to the terminal).
To stop it: **Ctrl+C** in that terminal, on any OS.

To run it in the background instead:

```bash
# Windows (PowerShell) - start detached, keep the PID to stop it later
Start-Process desireeia-server -ArgumentList "--model path\to\model.gguf --port 8080" -PassThru | Select-Object -ExpandProperty Id
# stop it:
Stop-Process -Id <pid>

# Linux / macOS - start detached, keep the PID to stop it later
desireeia-server --model path/to/model.gguf --port 8080 & echo $!
# stop it:
kill <pid>
```

### Dev install from the repo (instead of PyPI)

```bash
pip install <desireeia_source>/python <desireeia_source>/DesireeIAServer   # Windows: use \ instead of /
```

The engine, backend and sampling surface you can steer:

```bash
desireeia-server --model model.gguf --backend auto --threads 8 \
    --n-gpu-layers 0 --temperature 0.7 --top-k 40 --top-p 0.95 \
    --repeat-penalty 1.1 --n-predict 512
```

Run `desireeia-server --help` for the full surface.

## Layout

- `desireeiaserver/` — the package: `config.py` (CLI/env), `engine.py` (the
  DesireeIA adapter), `app.py` (FastAPI factory), `api/` (routes), `static/`
  (generated UI bundle, copied from `../ui` via `sync_static.py`).
- `../ui/` — the web UI source (single-page chat app).
- `../python/` — the `desireeia` engine wrapper this package depends on.

## Development

```bash
python -m venv .venv                      # repo root, gitignored
.venv/Scripts/pip install -e ./python
.venv/Scripts/pip install -e ./DesireeIAServer[dev]
.venv/Scripts/python -m pytest DesireeIAServer/tests
```

## Roadmap

See `../ProjectsRequirements.md` §10. Bootstrap status: HTTP scaffold,
`/health`, `/props`, `/v1/models` shape, UI placeholder, tests with an
in-memory mock engine. Streaming, router/slots, tools and the full UI land in
the next iterations.
