kiarina-llm 1.25.1

LLM utilities and context management for kiarina namespace

kiarina-llm

A Python library for LLM utilities and context management with type safety and configuration management.

Features

• AppContext Management: Application-level context for platform directories
• 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

pip install kiarina-llm

Quick Start

Basic Usage

from kiarina.llm.run_context import create_run_context

# Create a run context
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}")

Configuration

Configure defaults using pydantic-settings-manager:

from kiarina.llm.run_context import settings_manager

settings_manager.user_config = {
    "tenant_id": "default-tenant",
    "time_zone": "America/New_York",
    "language": "en"
}

Or use environment variables:

export KIARINA_LLM_RUN_CONTEXT_TENANT_ID="prod-tenant"
export KIARINA_LLM_RUN_CONTEXT_TIME_ZONE="Asia/Tokyo"

API Reference

AppContext

Application-level context for platform directories:

from kiarina.llm.app_context import get_app_context, settings_manager

# Configure app context
settings_manager.user_config = {
    "app_author": "MyCompany",
    "app_name": "MyAIApp"
}

# Get app context
app_context = get_app_context()
print(f"Author: {app_context.app_author}")
print(f"Name: {app_context.app_name}")

RunContext

Run-level context for LLM pipeline processing:

Field	Type	Description	Example
app_author	FSName	Application author	"MyCompany"
app_name	FSName	Application name	"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"
time_zone	str	IANA time zone	"Asia/Tokyo"
language	str	Language code	"ja"
currency	str	Currency code	"USD"
metadata	dict[str, Any]	Additional metadata	{"version": "1.0"}

Type Validation

• FSName: Filesystem-safe names (alphanumeric, dots, underscores, hyphens, spaces)
• IDStr: Identifier strings (alphanumeric, dots, underscores, hyphens)

Configuration Reference

AppContext Settings

Setting	Environment Variable	Default	Description
app_author	KIARINA_LLM_APP_CONTEXT_APP_AUTHOR	"kiarina"	Application author
app_name	KIARINA_LLM_APP_CONTEXT_APP_NAME	"kiarina-llm"	Application name

RunContext Settings

Setting	Environment Variable	Default	Description
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
currency	KIARINA_LLM_RUN_CONTEXT_CURRENCY	"USD"	Default currency code

Development

Prerequisites

• Python 3.12+

Setup

# 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

# 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 - Data validation using Python type hints
• pydantic-settings - Settings management
• 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 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 - The main monorepo containing this package
• pydantic-settings-manager - Configuration management library used by this package