Llimona 0.1.0.dev0__tar.gz

llimona-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.3
+Name: Llimona
+Version: 0.1.0.dev0
+Summary: Open and modular framework for building observable LLM gateways with OpenAI-compatible APIs and pluggable providers.
+Author: Alfred
+Author-email: Alfred <alfred82santa@gmail.com>
+Requires-Dist: click>=8.3.1
+Requires-Dist: litellm>=1.81.7
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.13.0
+Requires-Dist: pydantic-views>=0.3.0
+Requires-Dist: pymongo>=4.16.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Llimona
+
+Llimona is an open and modular Python framework for building production-ready LLM gateways.
+It provides OpenAI-compatible APIs, provider-aware routing, and an extensible plugin model for integrating multiple backends behind a single interface.
+
+By keeping providers as addons, Llimona stays lightweight at its core while enabling deployments to include only the integrations, policies, and observability components they actually need.
+
+## Key Features
+
+- OpenAI-compatible service interfaces (currently Responses and Models).
+- Provider routing using the `provider_name/model_name` naming convention.
+- Addon-based extensibility through Python entry points (`llimona.addon`).
+- Typed YAML configuration with Pydantic validation.
+- Request `Context` propagation with actor/origin metadata, constraints, and sub-context trees.
+- Sensor support for metrics such as request counters and elapsed time, making request execution observable.
+
+## Architecture
+
+[Architecture documentation](docs/arch.md)
+
+## Requirements
+
+- Python `>= 3.14`
+- `uv` (recommended)
+
+## Installation
+
+### Install dependencies for local development
+
+```bash
+uv sync
+```
+
+### Install the core package
+
+```bash
+uv pip install .
+```
+
+### Install an addon package
+
+```bash
+uv pip install ./addons/llimona_azure_openai
+```
+
+## Quick Start
+
+### 1) Create an app config
+
+Example (`test_config/app.yaml`):
+
+```yaml
+provider_addons:
+  - azure_openai
+provider_loaders:
+  - type: autodiscovery_dirs
+    src: !path .
+```
+
+### 2) Create a provider directory with `provider.yaml`
+
+Example (`example_config/azure_1/provider.yaml`):
+
+```yaml
+type: azure_openai
+name: azure_1
+display_name: Azure Example 1
+owner_id: 444444-222-333-222 # Not used, just for future purposes
+base_url: !envvar AZURE_OPENAI_1_BASE_URL
+credentials:
+  api_key: !envvar AZURE_OPENAI_1_API_KEY
+services:
+- type: openai_responses
+- type: openai_models
+models:
+- name: gpt-4o-mini
+  allowed_services:
+  - openai_responses
+```
+
+### 3) Run a request
+
+```bash
+uv run llimona app --config-file example_config/app.yaml openai responses create azure_1/gpt-4o-mini "Hello" --stream
+```
+
+### 4) Observe sensor metrics
+
+After the request completes, Llimona prints sensor values that make execution observable:
+
+```text
+Sensor value: elapsed_time=0.606314 (Elapsed time of the request.)
+Sensor value: request_count=1 (Number of requests being processed for the sensor request_count.)
+Sensor value: request_per_unit_of_time=1 (Number of requests in the last 0:01:00.)
+Sensor value: request_per_window_of_time=1 (Number of requests until the next reset.)
+```
+
+## CLI Usage
+
+### Top-level help
+
+```bash
+llimona --help
+```
+
+### List discovered addons
+
+```bash
+llimona addons
+```
+
+### Run commands with an app config
+
+```bash
+llimona app --config-file <path-to-app.yaml> <command>
+```
+
+### Providers
+
+```bash
+# list all providers
+llimona app --config-file <cfg> providers
+
+# inspect one provider
+llimona app --config-file <cfg> providers <provider_name>
+
+# list models in one provider
+llimona app --config-file <cfg> providers <provider_name> models
+```
+
+### OpenAI-compatible interface commands
+
+```bash
+# create a response
+llimona app --config-file <cfg> openai responses create <provider>/<model> "Prompt"
+
+# streaming response
+llimona app --config-file <cfg> openai responses create <provider>/<model> "Prompt" --stream
+
+# list models (global or filtered by provider)
+llimona app --config-file <cfg> openai models list
+llimona app --config-file <cfg> openai models list <provider_name>
+```
+
+## Configuration Overview
+
+The app configuration supports these top-level fields:
+
+- `provider_addons`: provider addons to register.
+- `provider_loader_addons`: provider-loader addons to register.
+- `sensor_addons`: sensor addons to register.
+- `id_builder`: optional ID builder configuration.
+- `provider_loaders`: loader definitions.
+
+Built-in provider loader:
+
+- `autodiscovery_dirs`: scans child directories under `src`, reads `provider.yaml`, and optionally merges definitions from `models/*.yaml`, `services/*.yaml`, and `sensors/*.yaml`.
+
+## Architecture Summary
+
+Llimona receives OpenAI-compatible requests, decomposes model IDs, routes to the appropriate provider, and maps provider-specific responses back to interface models.
+
+Every call flows through a `Context` object, which can carry:
+
+- action metadata (`provider`, `service`, `service_action`, `model`)
+- actor and origin information
+- conversation metadata
+- constraints
+- collected sensor values
+
+Routing strategies can create sub-contexts, enabling per-branch observability and post-execution failure inspection.
+
+Sensors make the platform observable by exposing execution metrics across the full request context tree.
+
+For full technical details, see `docs/arch.md`.
+
+## Addons in This Repository
+
+- `addons/llimona_azure_openai`: Azure OpenAI provider addon.
+- `addons/llimona_smart_provider`: smart/virtual provider routing addon.
+
+## Development
+
+### Install development tools
+
+```bash
+uv sync --group dev
+```
+
+### Run tests
+
+```bash
+uv run pytest
+```
+
+### Lint and format
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+## Branching and Versioning
+
+The repository follows a GitFlow-like model with:
+
+- `main` as the default integration branch
+- `feat/*`, `fix/*`, and `chore/*` working branches
+- squash-merge pull requests
+- SemVer/PEP 440 release semantics
+
+See [branching model document](BRANCHING_MODEL.md) for the complete policy.
+
+## Security Notes
+
+- Do not commit real API keys or secrets in provider files.
+- Inject credentials at runtime through your deployment environment.
+
+## License
+
+This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE. See `LICENSE` for details.

llimona-0.1.0.dev0/README.md

@@ -0,0 +1,221 @@
+# Llimona
+
+Llimona is an open and modular Python framework for building production-ready LLM gateways.
+It provides OpenAI-compatible APIs, provider-aware routing, and an extensible plugin model for integrating multiple backends behind a single interface.
+
+By keeping providers as addons, Llimona stays lightweight at its core while enabling deployments to include only the integrations, policies, and observability components they actually need.
+
+## Key Features
+
+- OpenAI-compatible service interfaces (currently Responses and Models).
+- Provider routing using the `provider_name/model_name` naming convention.
+- Addon-based extensibility through Python entry points (`llimona.addon`).
+- Typed YAML configuration with Pydantic validation.
+- Request `Context` propagation with actor/origin metadata, constraints, and sub-context trees.
+- Sensor support for metrics such as request counters and elapsed time, making request execution observable.
+
+## Architecture
+
+[Architecture documentation](docs/arch.md)
+
+## Requirements
+
+- Python `>= 3.14`
+- `uv` (recommended)
+
+## Installation
+
+### Install dependencies for local development
+
+```bash
+uv sync
+```
+
+### Install the core package
+
+```bash
+uv pip install .
+```
+
+### Install an addon package
+
+```bash
+uv pip install ./addons/llimona_azure_openai
+```
+
+## Quick Start
+
+### 1) Create an app config
+
+Example (`test_config/app.yaml`):
+
+```yaml
+provider_addons:
+  - azure_openai
+provider_loaders:
+  - type: autodiscovery_dirs
+    src: !path .
+```
+
+### 2) Create a provider directory with `provider.yaml`
+
+Example (`example_config/azure_1/provider.yaml`):
+
+```yaml
+type: azure_openai
+name: azure_1
+display_name: Azure Example 1
+owner_id: 444444-222-333-222 # Not used, just for future purposes
+base_url: !envvar AZURE_OPENAI_1_BASE_URL
+credentials:
+  api_key: !envvar AZURE_OPENAI_1_API_KEY
+services:
+- type: openai_responses
+- type: openai_models
+models:
+- name: gpt-4o-mini
+  allowed_services:
+  - openai_responses
+```
+
+### 3) Run a request
+
+```bash
+uv run llimona app --config-file example_config/app.yaml openai responses create azure_1/gpt-4o-mini "Hello" --stream
+```
+
+### 4) Observe sensor metrics
+
+After the request completes, Llimona prints sensor values that make execution observable:
+
+```text
+Sensor value: elapsed_time=0.606314 (Elapsed time of the request.)
+Sensor value: request_count=1 (Number of requests being processed for the sensor request_count.)
+Sensor value: request_per_unit_of_time=1 (Number of requests in the last 0:01:00.)
+Sensor value: request_per_window_of_time=1 (Number of requests until the next reset.)
+```
+
+## CLI Usage
+
+### Top-level help
+
+```bash
+llimona --help
+```
+
+### List discovered addons
+
+```bash
+llimona addons
+```
+
+### Run commands with an app config
+
+```bash
+llimona app --config-file <path-to-app.yaml> <command>
+```
+
+### Providers
+
+```bash
+# list all providers
+llimona app --config-file <cfg> providers
+
+# inspect one provider
+llimona app --config-file <cfg> providers <provider_name>
+
+# list models in one provider
+llimona app --config-file <cfg> providers <provider_name> models
+```
+
+### OpenAI-compatible interface commands
+
+```bash
+# create a response
+llimona app --config-file <cfg> openai responses create <provider>/<model> "Prompt"
+
+# streaming response
+llimona app --config-file <cfg> openai responses create <provider>/<model> "Prompt" --stream
+
+# list models (global or filtered by provider)
+llimona app --config-file <cfg> openai models list
+llimona app --config-file <cfg> openai models list <provider_name>
+```
+
+## Configuration Overview
+
+The app configuration supports these top-level fields:
+
+- `provider_addons`: provider addons to register.
+- `provider_loader_addons`: provider-loader addons to register.
+- `sensor_addons`: sensor addons to register.
+- `id_builder`: optional ID builder configuration.
+- `provider_loaders`: loader definitions.
+
+Built-in provider loader:
+
+- `autodiscovery_dirs`: scans child directories under `src`, reads `provider.yaml`, and optionally merges definitions from `models/*.yaml`, `services/*.yaml`, and `sensors/*.yaml`.
+
+## Architecture Summary
+
+Llimona receives OpenAI-compatible requests, decomposes model IDs, routes to the appropriate provider, and maps provider-specific responses back to interface models.
+
+Every call flows through a `Context` object, which can carry:
+
+- action metadata (`provider`, `service`, `service_action`, `model`)
+- actor and origin information
+- conversation metadata
+- constraints
+- collected sensor values
+
+Routing strategies can create sub-contexts, enabling per-branch observability and post-execution failure inspection.
+
+Sensors make the platform observable by exposing execution metrics across the full request context tree.
+
+For full technical details, see `docs/arch.md`.
+
+## Addons in This Repository
+
+- `addons/llimona_azure_openai`: Azure OpenAI provider addon.
+- `addons/llimona_smart_provider`: smart/virtual provider routing addon.
+
+## Development
+
+### Install development tools
+
+```bash
+uv sync --group dev
+```
+
+### Run tests
+
+```bash
+uv run pytest
+```
+
+### Lint and format
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+## Branching and Versioning
+
+The repository follows a GitFlow-like model with:
+
+- `main` as the default integration branch
+- `feat/*`, `fix/*`, and `chore/*` working branches
+- squash-merge pull requests
+- SemVer/PEP 440 release semantics
+
+See [branching model document](BRANCHING_MODEL.md) for the complete policy.
+
+## Security Notes
+
+- Do not commit real API keys or secrets in provider files.
+- Inject credentials at runtime through your deployment environment.
+
+## License
+
+This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE. See `LICENSE` for details.

llimona-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,189 @@
+[project]
+name = "Llimona"
+version = "0.1.0.dev0"
+description = "Open and modular framework for building observable LLM gateways with OpenAI-compatible APIs and pluggable providers."
+readme = "README.md"
+authors = [
+    { name = "Alfred", email = "alfred82santa@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "click>=8.3.1",
+    "litellm>=1.81.7",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.13.0",
+    "pydantic-views>=0.3.0",
+    "pymongo>=4.16.0",
+    "pyyaml>=6.0.3",
+]
+
+[project.scripts]
+llimona = "llimona.cli:llimona"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+cron = [
+    "cronsim>=2.7",
+]
+crypt = [
+    "pycryptodome>=3.23.0",
+]
+dev = [
+    "mypy>=1.19.1",
+    "poethepoet>=0.42.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.14",
+    "types-croniter>=6.0.0.20250809",
+    "types-pyyaml>=6.0.12.20250915",
+]
+timezone = [
+    "pydantic-extra-types>=2.11.0",
+    "pydantic[timezone]>=2.12.5",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+exclude = [".venv", "dist", "build"]
+force-exclude = true
+
+[tool.ruff.lint]
+# Rules to enforce
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "N",   # pep8-naming
+    "B",   # flake8-bugbear
+    "A",   # flake8-builtins
+    "C4",  # flake8-comprehensions
+    "PT",  # flake8-pytest-style
+    "RUF", # Ruff-specific rules
+]
+
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+
+[tool.uv.workspace]
+members = [
+    "addons/llimona_azure_openai",
+    "addons/llimona_smart_provider",
+    "addons/llimona_mock_provider",
+    "addons/llimona_opentelemetry",
+]
+
+[tool.coverage.run]
+omit = [".venv/*", "tests/**", "src/**/cli/**"]
+source = ["src"]
+branch = true
+relative_files = false
+
+[tool.coverage.report]
+# Regexes for lines to exclude from consideration
+exclude_also = [
+    # Don't complain about missing debug-only code:
+    "def __repr__",
+    "if self\\.debug",
+
+    # Don't complain if tests don't hit defensive assertion code:
+    "raise AssertionError",
+    "raise NotImplementedError",
+
+    # Don't complain if non-runnable code isn't run:
+    "if 0:",
+    "if __name__ == .__main__.:",
+
+    # Don't complain about abstract methods, they aren't run:
+    "@(abc\\.)?abstractmethod",
+
+    # Don't complain type checking imports, they aren't run:
+    "if TYPE_CHECKING",
+
+    # Don't complain overloads, they aren't run:
+    "@overload"
+]
+
+[tool.coverage.paths]
+source = ["src/"]
+omit = [
+    "src/**/cli",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+asyncio_mode = "auto"
+addopts = ["--strict-markers", "--strict-config"]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.poe.tasks]
+build = "uv build"
+test = "pytest -v -s --junitxml=pytest.xml --cov src --cov-report term-missing --cov-report xml:coverage.xml --cov-fail-under=85 --exitfirst"
+typecheck = "mypy src"
+format = "ruff format src tests"
+"format:check" = "ruff format src tests --check"
+lint = "ruff check src tests"
+"lint:fix" = "ruff check src tests --fix"
+
+[tool.poe.tasks.clean]
+cmd = """
+rm -rf ./**/src/**/*.pyc
+       ./**/src/**/*.pyo
+       ./**/src/**/__pycache__
+       ./**/tests/**/*.pyc
+       ./**/tests/**/*.pyo
+       ./**/tests/**/__pycache__
+       .coverage
+       coverage.xml
+       pytest.xml
+       .*_cache
+"""
+empty_glob = "null"
+
+[tool.poe.tasks.validate]
+help = "Execute all validations: typecheck, lint, and test"
+sequence = [
+    "typecheck",
+    "lint",
+    "test"
+]
+
+[tool.poe.tasks.prebuild]
+help = "Pre-build checks: typecheck and lint"
+sequence = [
+    "typecheck", 
+    "lint"
+]
+
+[tool.poe.tasks."clean:all"]
+help = "Complete cleanup: cache, coverage, and temporary files"
+sequence = [
+    "clean",
+    { cmd = """rm -rf dist
+                      build
+                      .coverage
+                      coverage.xml
+                      pytest.xml
+                      **/.*_cache
+            """},
+]
+
+[tool.poe.tasks.fix]
+help = "Fix linting and formatting issues, then run tests"
+sequence = [
+    "format",
+    "lint:fix",
+]

llimona-0.1.0.dev0/src/llimona/__init__.py

@@ -0,0 +1,4 @@
+def init():
+    from .addons import Addons
+
+    Addons().register_all_providers()