Metadata-Version: 2.5
Name: lilla-core
Version: 0.5.1
Summary: Core runtime of the Lilla agent
Project-URL: Homepage, https://github.com/tettekai/lilla-core
Project-URL: Repository, https://github.com/tettekai/lilla-core
Project-URL: Issues, https://github.com/tettekai/lilla-core/issues
Author: tettekai
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,bot,discord,llm
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: aiohttp==3.11.14
Requires-Dist: apscheduler==3.11.0
Requires-Dist: bcrypt==5.0.0
Requires-Dist: discord-py==2.4.0
Requires-Dist: motor==3.7.0
Requires-Dist: pydantic-settings==2.8.1
Requires-Dist: pydantic==2.11.1
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: pyyaml==6.0.2
Requires-Dist: tiktoken==0.9.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
Requires-Dist: pytest==9.0.2; extra == 'dev'
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/tettekai/lilla-core/main/docs/lilla-logo.png" alt="Lilla" width="160" />

# lilla-core

> This README is a translation of the Japanese original,
> [README.ja.md](https://github.com/tettekai/lilla-core/blob/main/README.ja.md). If the two
> differ, the Japanese version is authoritative.

A core runtime for AI agents: it runs as a Discord bot and handles the tool_call loop
with an LLM (Ollama / OpenAI-compatible), command processing, and replies.

> **Note:** Conversation history, the active LLM provider, and session memory are **shared
> process-wide**, not split per channel or per user. lilla-core assumes a single owner
> talking to one bot process; it is not built for multi-user or multi-tenant use.

## Requirements

- Python 3.12 or later
- MongoDB
- A Discord bot token

## Install and run

```bash
pip install lilla-core

export CONFIG_ROOT=/path/to/config   # the directory holding lilla.yaml
export DISCORD_TOKEN=...
export MONGODB_URI=mongodb://...

python -m lilla_core.bot
```

Put `lilla.yaml` in the `CONFIG_ROOT` directory. See the documentation for how to write
it and how to set up the bot on the Discord side.

## Extensions

List module import paths, comma-separated, in the `LILLA_EXTENSIONS` environment variable
and they are loaded as extensions at startup. Leave it unset and the core runs on its own
as a Discord bot.

An extension subclasses `lilla_core.core.extension.Extension`, overrides only the methods
it needs, and exposes itself from its module as `extension = MyExtension()`.

Google OAuth (`lilla_core.extensions.google_oauth`) and Google Calendar
(`lilla_core.extensions.google_calendar`) ship with the core as an official extension pack. Each is
loaded only when listed in `LILLA_EXTENSIONS`.

## Optional decision helper (Jev)

`ask_jev()` in `lilla_core.tool_support.jev` is a thin helper that sends a state and typed
questions (Choice / Score / Noul) to TypeSafe's System One model (Jev) and returns answers with
probabilities. Use it where you need a fast pick from a fixed set of answers, such as a gate
before running a tool or model selection in an LLM resolver. The core does not depend on this
API, and the TypeSafe SDK is not a required dependency. Only code that imports the helper calls
it; the API key comes from an argument or the `TYPESAFE_API_KEY` environment variable. See
[Decision helper (Jev)](https://github.com/tettekai/lilla-core/blob/main/docs/en/jev.md).

## Documentation

- [Documentation index](https://github.com/tettekai/lilla-core/blob/main/docs/en/README.md)
- [Issues](https://github.com/tettekai/lilla-core/issues)

## License

MIT
