# kiarina-llm
A Python library for LLM utilities and context management with type safety and configuration management.
## Features
- **RunContext Management**: Structured context information for LLM pipeline processing
- **Type Safety**: Full type hints and Pydantic validation
- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration
- **Filesystem Safe Names**: Validated names for cross-platform compatibility
- **ID Validation**: Structured ID types with pattern validation
## Installation
```bash
pip install kiarina-llm
```
## Quick Start
### Basic RunContext Usage
```python
from kiarina.llm.run_context import create_run_context
# Create a run context with default settings
context = create_run_context(
tenant_id="tenant-123",
user_id="user-456",
agent_id="my-agent",
time_zone="Asia/Tokyo",
language="ja"
)
print(f"User: {context.user_id}")
print(f"Agent: {context.agent_id}")
print(f"Time Zone: {context.time_zone}")
print(f"Language: {context.language}")
```
### Configuration Management
```python
from kiarina.llm.run_context import settings_manager
# Configure default values
settings_manager.user_config = {
"app_author": "MyCompany",
"app_name": "MyAIApp",
"tenant_id": "default-tenant",
"user_id": "default-user",
"time_zone": "America/New_York",
"language": "en"
}
# Create context with configured defaults
context = create_run_context(
agent_id="specialized-agent" # Override only specific values
)
```
### Environment Variable Configuration
Configure defaults using environment variables:
```bash
export KIARINA_LLM_RUN_CONTEXT_APP_AUTHOR="MyCompany"
export KIARINA_LLM_RUN_CONTEXT_APP_NAME="MyAIApp"
export KIARINA_LLM_RUN_CONTEXT_TENANT_ID="prod-tenant"
export KIARINA_LLM_RUN_CONTEXT_TIME_ZONE="Asia/Tokyo"
export KIARINA_LLM_RUN_CONTEXT_LANGUAGE="ja"
```
## RunContext Fields
The `RunContext` model includes the following fields:
| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `app_author` | `FSName` | Application author (filesystem safe) | `"MyCompany"` |
| `app_name` | `FSName` | Application name (filesystem safe) | `"MyAIApp"` |
| `tenant_id` | `IDStr` | Tenant identifier | `"tenant-123"` |
| `user_id` | `IDStr` | User identifier | `"user-456"` |
| `agent_id` | `IDStr` | Agent identifier | `"my-agent"` |
| `runner_id` | `IDStr` | Runner identifier | `"linux"` (auto-detected) |
| `time_zone` | `str` | IANA time zone | `"Asia/Tokyo"` |
| `language` | `str` | ISO 639-1 language code | `"ja"` |
| `metadata` | `dict[str, Any]` | Additional metadata | `{"version": "1.0"}` |
## Type Validation
### FSName (Filesystem Safe Name)
The `FSName` type ensures names are safe for use across different filesystems:
```python
from kiarina.llm.run_context import create_run_context
# Valid names
context = create_run_context(
app_author="My Company", # Spaces allowed
app_name="My-App_v1.0" # Hyphens, underscores, dots allowed
)
# Invalid names (will raise ValidationError)
try:
create_run_context(app_author="My App.") # Ends with dot
except ValueError as e:
print(f"Validation error: {e}")
try:
create_run_context(app_author=".hidden") # Starts with dot
except ValueError as e:
print(f"Validation error: {e}")
try:
create_run_context(app_author="CON") # Windows reserved name
except ValueError as e:
print(f"Validation error: {e}")
```
### IDStr (ID String)
The `IDStr` type validates identifiers:
```python
# Valid IDs
context = create_run_context(
tenant_id="tenant-123",
user_id="user.456",
agent_id="agent_v1.0"
)
# Invalid IDs (will raise ValidationError)
try:
create_run_context(tenant_id="") # Empty string
except ValueError as e:
print(f"Validation error: {e}")
try:
create_run_context(user_id="user@domain") # Invalid character
except ValueError as e:
print(f"Validation error: {e}")
```
## Advanced Usage
### Custom Metadata
```python
context = create_run_context(
tenant_id="tenant-123",
user_id="user-456",
metadata={
"session_id": "session-789",
"request_id": "req-abc123",
"version": "1.0.0",
"features": ["feature-a", "feature-b"]
}
)
print(f"Session: {context.metadata['session_id']}")
print(f"Features: {context.metadata['features']}")
```
### Integration with PlatformDirs
The `app_author` and `app_name` fields are designed to work with libraries like `platformdirs`:
```python
from platformdirs import user_data_dir
from kiarina.llm.run_context import create_run_context
context = create_run_context(
app_author="MyCompany",
app_name="MyAIApp"
)
# Use with platformdirs
data_dir = user_data_dir(
appname=context.app_name,
appauthor=context.app_author
)
print(f"Data directory: {data_dir}")
```
## Configuration Reference
| Setting | Environment Variable | Default | Description |
|---------|---------------------|---------|-------------|
| `app_author` | `KIARINA_LLM_RUN_CONTEXT_APP_AUTHOR` | `"kiarina"` | Default application author |
| `app_name` | `KIARINA_LLM_RUN_CONTEXT_APP_NAME` | `"myaikit"` | Default application name |
| `tenant_id` | `KIARINA_LLM_RUN_CONTEXT_TENANT_ID` | `""` | Default tenant ID |
| `user_id` | `KIARINA_LLM_RUN_CONTEXT_USER_ID` | `""` | Default user ID |
| `agent_id` | `KIARINA_LLM_RUN_CONTEXT_AGENT_ID` | `""` | Default agent ID |
| `runner_id` | `KIARINA_LLM_RUN_CONTEXT_RUNNER_ID` | `platform.system().lower()` | Default runner ID |
| `time_zone` | `KIARINA_LLM_RUN_CONTEXT_TIME_ZONE` | `"UTC"` | Default time zone |
| `language` | `KIARINA_LLM_RUN_CONTEXT_LANGUAGE` | `"en"` | Default language |
## Development
### Prerequisites
- Python 3.12+
### Setup
```bash
# Clone the repository
git clone https://github.com/kiarina/kiarina-python.git
cd kiarina-python
# Setup development environment (installs tools, syncs dependencies, downloads test data)
mise run setup
```
### Running Tests
```bash
# Run format, lint, type checks and tests
mise run package kiarina-llm
# Coverage report
mise run package:test kiarina-llm --coverage
# Run specific tests
uv run --group test pytest packages/kiarina-llm/tests/run_context/
```
## Dependencies
- [pydantic](https://docs.pydantic.dev/) - Data validation using Python type hints
- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management
- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management
## Roadmap
This package is in active development. Planned features include:
- **Chat Model Management**: Unified interface for different LLM providers
- **Agent Framework**: Tools for building LLM agents
- **Pipeline Management**: Workflow management for LLM processing
- **Memory Management**: Context and conversation memory handling
- **Tool Integration**: Framework for LLM tool calling
## License
This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
## Contributing
This is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.
## Related Projects
- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package
- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package
Raw data
{
"_id": null,
"home_page": null,
"name": "kiarina-llm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "kiarina <kiarinadawa@gmail.com>",
"keywords": "agent, ai, context, llm, pydantic, runner, settings",
"author": null,
"author_email": "kiarina <kiarinadawa@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/99/89/ad4b9e9171614ce835eaf876b8d0a4e0461096ff42aa02851ae2189dfc84/kiarina_llm-1.0.1.tar.gz",
"platform": null,
"description": "# kiarina-llm\n\nA Python library for LLM utilities and context management with type safety and configuration management.\n\n## Features\n\n- **RunContext Management**: Structured context information for LLM pipeline processing\n- **Type Safety**: Full type hints and Pydantic validation\n- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration\n- **Filesystem Safe Names**: Validated names for cross-platform compatibility\n- **ID Validation**: Structured ID types with pattern validation\n\n## Installation\n\n```bash\npip install kiarina-llm\n```\n\n## Quick Start\n\n### Basic RunContext Usage\n\n```python\nfrom kiarina.llm.run_context import create_run_context\n\n# Create a run context with default settings\ncontext = create_run_context(\n tenant_id=\"tenant-123\",\n user_id=\"user-456\",\n agent_id=\"my-agent\",\n time_zone=\"Asia/Tokyo\",\n language=\"ja\"\n)\n\nprint(f\"User: {context.user_id}\")\nprint(f\"Agent: {context.agent_id}\")\nprint(f\"Time Zone: {context.time_zone}\")\nprint(f\"Language: {context.language}\")\n```\n\n### Configuration Management\n\n```python\nfrom kiarina.llm.run_context import settings_manager\n\n# Configure default values\nsettings_manager.user_config = {\n \"app_author\": \"MyCompany\",\n \"app_name\": \"MyAIApp\",\n \"tenant_id\": \"default-tenant\",\n \"user_id\": \"default-user\",\n \"time_zone\": \"America/New_York\",\n \"language\": \"en\"\n}\n\n# Create context with configured defaults\ncontext = create_run_context(\n agent_id=\"specialized-agent\" # Override only specific values\n)\n```\n\n### Environment Variable Configuration\n\nConfigure defaults using environment variables:\n\n```bash\nexport KIARINA_LLM_RUN_CONTEXT_APP_AUTHOR=\"MyCompany\"\nexport KIARINA_LLM_RUN_CONTEXT_APP_NAME=\"MyAIApp\"\nexport KIARINA_LLM_RUN_CONTEXT_TENANT_ID=\"prod-tenant\"\nexport KIARINA_LLM_RUN_CONTEXT_TIME_ZONE=\"Asia/Tokyo\"\nexport KIARINA_LLM_RUN_CONTEXT_LANGUAGE=\"ja\"\n```\n\n## RunContext Fields\n\nThe `RunContext` model includes the following fields:\n\n| Field | Type | Description | Example |\n|-------|------|-------------|---------|\n| `app_author` | `FSName` | Application author (filesystem safe) | `\"MyCompany\"` |\n| `app_name` | `FSName` | Application name (filesystem safe) | `\"MyAIApp\"` |\n| `tenant_id` | `IDStr` | Tenant identifier | `\"tenant-123\"` |\n| `user_id` | `IDStr` | User identifier | `\"user-456\"` |\n| `agent_id` | `IDStr` | Agent identifier | `\"my-agent\"` |\n| `runner_id` | `IDStr` | Runner identifier | `\"linux\"` (auto-detected) |\n| `time_zone` | `str` | IANA time zone | `\"Asia/Tokyo\"` |\n| `language` | `str` | ISO 639-1 language code | `\"ja\"` |\n| `metadata` | `dict[str, Any]` | Additional metadata | `{\"version\": \"1.0\"}` |\n\n## Type Validation\n\n### FSName (Filesystem Safe Name)\n\nThe `FSName` type ensures names are safe for use across different filesystems:\n\n```python\nfrom kiarina.llm.run_context import create_run_context\n\n# Valid names\ncontext = create_run_context(\n app_author=\"My Company\", # Spaces allowed\n app_name=\"My-App_v1.0\" # Hyphens, underscores, dots allowed\n)\n\n# Invalid names (will raise ValidationError)\ntry:\n create_run_context(app_author=\"My App.\") # Ends with dot\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\n\ntry:\n create_run_context(app_author=\".hidden\") # Starts with dot\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\n\ntry:\n create_run_context(app_author=\"CON\") # Windows reserved name\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\n```\n\n### IDStr (ID String)\n\nThe `IDStr` type validates identifiers:\n\n```python\n# Valid IDs\ncontext = create_run_context(\n tenant_id=\"tenant-123\",\n user_id=\"user.456\",\n agent_id=\"agent_v1.0\"\n)\n\n# Invalid IDs (will raise ValidationError)\ntry:\n create_run_context(tenant_id=\"\") # Empty string\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\n\ntry:\n create_run_context(user_id=\"user@domain\") # Invalid character\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\n```\n\n## Advanced Usage\n\n### Custom Metadata\n\n```python\ncontext = create_run_context(\n tenant_id=\"tenant-123\",\n user_id=\"user-456\",\n metadata={\n \"session_id\": \"session-789\",\n \"request_id\": \"req-abc123\",\n \"version\": \"1.0.0\",\n \"features\": [\"feature-a\", \"feature-b\"]\n }\n)\n\nprint(f\"Session: {context.metadata['session_id']}\")\nprint(f\"Features: {context.metadata['features']}\")\n```\n\n### Integration with PlatformDirs\n\nThe `app_author` and `app_name` fields are designed to work with libraries like `platformdirs`:\n\n```python\nfrom platformdirs import user_data_dir\nfrom kiarina.llm.run_context import create_run_context\n\ncontext = create_run_context(\n app_author=\"MyCompany\",\n app_name=\"MyAIApp\"\n)\n\n# Use with platformdirs\ndata_dir = user_data_dir(\n appname=context.app_name,\n appauthor=context.app_author\n)\nprint(f\"Data directory: {data_dir}\")\n```\n\n## Configuration Reference\n\n| Setting | Environment Variable | Default | Description |\n|---------|---------------------|---------|-------------|\n| `app_author` | `KIARINA_LLM_RUN_CONTEXT_APP_AUTHOR` | `\"kiarina\"` | Default application author |\n| `app_name` | `KIARINA_LLM_RUN_CONTEXT_APP_NAME` | `\"myaikit\"` | Default application name |\n| `tenant_id` | `KIARINA_LLM_RUN_CONTEXT_TENANT_ID` | `\"\"` | Default tenant ID |\n| `user_id` | `KIARINA_LLM_RUN_CONTEXT_USER_ID` | `\"\"` | Default user ID |\n| `agent_id` | `KIARINA_LLM_RUN_CONTEXT_AGENT_ID` | `\"\"` | Default agent ID |\n| `runner_id` | `KIARINA_LLM_RUN_CONTEXT_RUNNER_ID` | `platform.system().lower()` | Default runner ID |\n| `time_zone` | `KIARINA_LLM_RUN_CONTEXT_TIME_ZONE` | `\"UTC\"` | Default time zone |\n| `language` | `KIARINA_LLM_RUN_CONTEXT_LANGUAGE` | `\"en\"` | Default language |\n\n## Development\n\n### Prerequisites\n\n- Python 3.12+\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kiarina/kiarina-python.git\ncd kiarina-python\n\n# Setup development environment (installs tools, syncs dependencies, downloads test data)\nmise run setup\n```\n\n### Running Tests\n\n```bash\n# Run format, lint, type checks and tests\nmise run package kiarina-llm\n\n# Coverage report\nmise run package:test kiarina-llm --coverage\n\n# Run specific tests\nuv run --group test pytest packages/kiarina-llm/tests/run_context/\n```\n\n## Dependencies\n\n- [pydantic](https://docs.pydantic.dev/) - Data validation using Python type hints\n- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management\n- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management\n\n## Roadmap\n\nThis package is in active development. Planned features include:\n\n- **Chat Model Management**: Unified interface for different LLM providers\n- **Agent Framework**: Tools for building LLM agents\n- **Pipeline Management**: Workflow management for LLM processing\n- **Memory Management**: Context and conversation memory handling\n- **Tool Integration**: Framework for LLM tool calling\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.\n\n## Contributing\n\nThis is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.\n\n## Related Projects\n\n- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package\n- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "LLM utilities and context management for kiarina namespace",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-llm/CHANGELOG.md",
"Documentation": "https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-llm#readme",
"Homepage": "https://github.com/kiarina/kiarina-python",
"Issues": "https://github.com/kiarina/kiarina-python/issues",
"Repository": "https://github.com/kiarina/kiarina-python"
},
"split_keywords": [
"agent",
" ai",
" context",
" llm",
" pydantic",
" runner",
" settings"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bc7b9aa39659933fb1f89d9598ee4f6f62ae5a536c15b65928a579ac5e438dbe",
"md5": "671bdd8cecd4fc3b5cc0e98b8fbf6bac",
"sha256": "a6d8e488669bac349016b956819018f2ea8195709505b1844fe1cdb386c25a0f"
},
"downloads": -1,
"filename": "kiarina_llm-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "671bdd8cecd4fc3b5cc0e98b8fbf6bac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 7676,
"upload_time": "2025-09-11T08:52:25",
"upload_time_iso_8601": "2025-09-11T08:52:25.288977Z",
"url": "https://files.pythonhosted.org/packages/bc/7b/9aa39659933fb1f89d9598ee4f6f62ae5a536c15b65928a579ac5e438dbe/kiarina_llm-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9989ad4b9e9171614ce835eaf876b8d0a4e0461096ff42aa02851ae2189dfc84",
"md5": "6d899ad53ab982c3563c9cb7acc4c037",
"sha256": "f0915dec72b2273dd184b7e652a1f91af7ba638b5188089e5924ea63982deb6d"
},
"downloads": -1,
"filename": "kiarina_llm-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6d899ad53ab982c3563c9cb7acc4c037",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 7599,
"upload_time": "2025-09-11T08:52:30",
"upload_time_iso_8601": "2025-09-11T08:52:30.649685Z",
"url": "https://files.pythonhosted.org/packages/99/89/ad4b9e9171614ce835eaf876b8d0a4e0461096ff42aa02851ae2189dfc84/kiarina_llm-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 08:52:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiarina",
"github_project": "kiarina-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kiarina-llm"
}
JSON
