{"id":48751302,"url":"https://github.com/llimona-org/llimona","last_synced_at":"2026-04-25T01:12:08.492Z","repository":{"id":350657134,"uuid":"1207750485","full_name":"llimona-org/llimona","owner":"llimona-org","description":"Llimona is an open and modular Python framework for building production-ready LLM gateways","archived":false,"fork":false,"pushed_at":"2026-04-20T10:42:52.000Z","size":131,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-20T10:43:08.294Z","etag":null,"topics":["asyncio","llm","llm-gateway","llm-proxy","llm-tools","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/llimona-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T10:55:28.000Z","updated_at":"2026-04-20T10:42:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/llimona-org/llimona","commit_stats":null,"previous_names":["llimona-org/llimona"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/llimona-org/llimona","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llimona-org%2Fllimona","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llimona-org%2Fllimona/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llimona-org%2Fllimona/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llimona-org%2Fllimona/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/llimona-org","download_url":"https://codeload.github.com/llimona-org/llimona/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llimona-org%2Fllimona/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32246431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","llm","llm-gateway","llm-proxy","llm-tools","python"],"created_at":"2026-04-12T19:16:46.221Z","updated_at":"2026-04-25T01:12:08.462Z","avatar_url":"https://github.com/llimona-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Llimona\n\nLlimona is an open and modular Python framework for building production-ready LLM gateways.\nIt provides OpenAI-compatible APIs, provider-aware routing, and an extensible plugin model for integrating multiple backends behind a single interface.\n\nBy 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.\n\n## Key Features\n\n- OpenAI-compatible service interfaces (currently Responses and Models).\n- Provider routing using the `provider_name/model_name` naming convention.\n- Addon-based extensibility through Python entry points (`llimona.addon`).\n- Typed YAML configuration with Pydantic validation.\n- Request `Context` propagation with actor/origin metadata, constraints, and sub-context trees.\n- Sensor support for metrics such as request counters and elapsed time, making request execution observable.\n\n## Architecture\n\n[Architecture documentation](docs/arch.md)\n\n## Requirements\n\n- Python `\u003e= 3.14`\n- `uv` (recommended)\n\n## Installation\n\n### Install dependencies for local development\n\n```bash\nuv sync\n```\n\n### Install the core package\n\n```bash\nuv pip install .\n```\n\n### Install an addon package\n\n```bash\nuv pip install ./addons/llimona_azure_openai\n```\n\n## Quick Start\n\n### 1) Create an app config\n\nExample (`test_config/app.yaml`):\n\n```yaml\nprovider_addons:\n  - azure_openai\nprovider_loaders:\n  - type: autodiscovery_dirs\n    src: !path .\n```\n\n### 2) Create a provider directory with `provider.yaml`\n\nExample (`example_config/azure_1/provider.yaml`):\n\n```yaml\ntype: azure_openai\nname: azure_1\ndisplay_name: Azure Example 1\nowner_id: 444444-222-333-222 # Not used, just for future purposes\nbase_url: !envvar AZURE_OPENAI_1_BASE_URL\ncredentials:\n  api_key: !envvar AZURE_OPENAI_1_API_KEY\nservices:\n- type: openai_responses\n- type: openai_models\nmodels:\n- name: gpt-4o-mini\n  allowed_services:\n  - openai_responses\n```\n\n### 3) Run a request\n\n```bash\nuv run llimona app --config-file example_config/app.yaml openai responses create azure_1/gpt-4o-mini \"Hello\" --stream\n```\n\n### 4) Observe sensor metrics\n\nAfter the request completes, Llimona prints sensor values that make execution observable:\n\n```text\nSensor value: elapsed_time=0.606314 (Elapsed time of the request.)\nSensor value: request_count=1 (Number of requests being processed for the sensor request_count.)\nSensor value: request_per_unit_of_time=1 (Number of requests in the last 0:01:00.)\nSensor value: request_per_window_of_time=1 (Number of requests until the next reset.)\n```\n\n## CLI Usage\n\n### Top-level help\n\n```bash\nllimona --help\n```\n\n### List discovered addons\n\n```bash\nllimona addons\n```\n\n### Run commands with an app config\n\n```bash\nllimona app --config-file \u003cpath-to-app.yaml\u003e \u003ccommand\u003e\n```\n\n### Providers\n\n```bash\n# list all providers\nllimona app --config-file \u003ccfg\u003e providers\n\n# inspect one provider\nllimona app --config-file \u003ccfg\u003e providers \u003cprovider_name\u003e\n\n# list models in one provider\nllimona app --config-file \u003ccfg\u003e providers \u003cprovider_name\u003e models\n```\n\n### OpenAI-compatible interface commands\n\n```bash\n# create a response\nllimona app --config-file \u003ccfg\u003e openai responses create \u003cprovider\u003e/\u003cmodel\u003e \"Prompt\"\n\n# streaming response\nllimona app --config-file \u003ccfg\u003e openai responses create \u003cprovider\u003e/\u003cmodel\u003e \"Prompt\" --stream\n\n# list models (global or filtered by provider)\nllimona app --config-file \u003ccfg\u003e openai models list\nllimona app --config-file \u003ccfg\u003e openai models list \u003cprovider_name\u003e\n```\n\n## Configuration Overview\n\nThe app configuration supports these top-level fields:\n\n- `provider_addons`: provider addons to register.\n- `provider_loader_addons`: provider-loader addons to register.\n- `sensor_addons`: sensor addons to register.\n- `id_builder`: optional ID builder configuration.\n- `provider_loaders`: loader definitions.\n\nBuilt-in provider loader:\n\n- `autodiscovery_dirs`: scans child directories under `src`, reads `provider.yaml`, and optionally merges definitions from `models/*.yaml`, `services/*.yaml`, and `sensors/*.yaml`.\n\n## Architecture Summary\n\nLlimona receives OpenAI-compatible requests, decomposes model IDs, routes to the appropriate provider, and maps provider-specific responses back to interface models.\n\nEvery call flows through a `Context` object, which can carry:\n\n- action metadata (`provider`, `service`, `service_action`, `model`)\n- actor and origin information\n- conversation metadata\n- constraints\n- collected sensor values\n\nRouting strategies can create sub-contexts, enabling per-branch observability and post-execution failure inspection.\n\nSensors make the platform observable by exposing execution metrics across the full request context tree.\n\nFor full technical details, see `docs/arch.md`.\n\n## Addons in This Repository\n\n- `addons/llimona_azure_openai`: Azure OpenAI provider addon.\n- `addons/llimona_smart_provider`: smart/virtual provider routing addon.\n\n## Development\n\n### Install development tools\n\n```bash\nuv sync --group dev\n```\n\n### Run tests\n\n```bash\npoe test\n```\n\n### Lint and format\n\n```bash\npoe fix\n```\n\n## Branching and Versioning\n\nThe repository follows a GitFlow-like model with:\n\n- `main` as the default integration branch\n- `feat/*`, `fix/*`, and `chore/*` working branches\n- squash-merge pull requests\n- SemVer/PEP 440 release semantics\n\nSee [branching model document](BRANCHING_MODEL.md) for the complete policy.\n\n## Security Notes\n\n- Do not commit real API keys or secrets in provider files.\n- Inject credentials at runtime through your deployment environment.\n\n## License\n\nThis project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE. See `LICENSE` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllimona-org%2Fllimona","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllimona-org%2Fllimona","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllimona-org%2Fllimona/lists"}