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:

Type Validation

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

Configuration Reference

AppContext Settings

RunContext Settings

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