kiarina-llm 1.0.0__tar.gz

kiarina_llm-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# uv
+.uv_cache/
+
+# Virtual environments & config
+.venv/
+.env
+
+# IDE
+.vscode/
+*.code-workspace
+
+# OS
+.DS_Store
+
+# Project specific
+*.log
+tmp/
+ai.yaml
+
+# Test data
+tests/data/large/
+
+# mise tasks (always include)
+!mise-tasks/
+!mise-tasks/**

kiarina_llm-1.0.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-09-09
+
+### Added
+- Initial release of kiarina-llm
+- RunContext management for LLM pipeline processing
+- Type-safe FSName validation for filesystem-safe names
+- Type-safe IDStr validation for identifiers
+- Configuration management using pydantic-settings-manager
+- Environment variable configuration support
+- Runtime configuration overrides
+- Cross-platform compatibility with Windows reserved name validation
+- Full type hints and Pydantic validation
+- Comprehensive test suite
+
+### Features
+- **RunContext**: Structured context information holder
+  - Application author and name (filesystem safe)
+  - Tenant, user, agent, and runner identifiers
+  - Time zone and language settings
+  - Extensible metadata support
+- **Type Safety**: Custom Pydantic types for validation
+  - FSName: Filesystem-safe names with cross-platform validation
+  - IDStr: Identifier strings with pattern validation
+- **Configuration**: Flexible settings management
+  - Environment variable support with KIARINA_LLM_RUN_CONTEXT_ prefix
+  - Runtime configuration overrides
+  - Default value management
+
+### Dependencies
+- pydantic>=2.10.1
+- pydantic-settings>=2.10.1
+- pydantic-settings-manager>=2.1.0

kiarina_llm-1.0.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: kiarina-llm
+Version: 1.0.0
+Summary: LLM utilities and context management for kiarina namespace
+Project-URL: Homepage, https://github.com/kiarina/kiarina-python
+Project-URL: Repository, https://github.com/kiarina/kiarina-python
+Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
+Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-llm/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-llm#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License: MIT
+Keywords: agent,ai,context,llm,pydantic,runner,settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic-settings-manager>=2.1.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic>=2.10.1
+Description-Content-Type: text/markdown
+
+# 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

kiarina_llm-1.0.0/README.md

@@ -0,0 +1,257 @@
+# 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

kiarina_llm-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "kiarina-llm"
+version = "1.0.0"
+description = "LLM utilities and context management for kiarina namespace"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "kiarina", email = "kiarinadawa@gmail.com" }
+]
+maintainers = [
+    { name = "kiarina", email = "kiarinadawa@gmail.com" }
+]
+keywords = ["llm", "ai", "context", "pydantic", "settings", "agent", "runner"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.10.1",
+    "pydantic-settings>=2.10.1",
+    "pydantic-settings-manager>=2.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/kiarina/kiarina-python"
+Repository = "https://github.com/kiarina/kiarina-python"
+Issues = "https://github.com/kiarina/kiarina-python/issues"
+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"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kiarina"]

kiarina_llm-1.0.0/src/kiarina/llm/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("kiarina-llm")

kiarina_llm-1.0.0/src/kiarina/llm/run_context/__init__.py

@@ -0,0 +1,9 @@
+from ._model import RunContext
+from ._registry import create_run_context
+from .settings import settings_manager
+
+__all__ = [
+    "create_run_context",
+    "RunContext",
+    "settings_manager",
+]

kiarina_llm-1.0.0/src/kiarina/llm/run_context/_model.py

@@ -0,0 +1,76 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ._types.fs_name import FSName
+from ._types.id_str import IDStr
+
+
+class RunContext(BaseModel):
+    """
+    Run Context
+
+    Holds the context information used in the LLM pipeline processing.
+    """
+
+    app_author: FSName
+    """
+    Application author
+
+    Used in PlatformDirs.
+    """
+
+    app_name: FSName
+    """
+    Application name
+
+    Used in PlatformDirs.
+    """
+
+    tenant_id: IDStr
+    """
+    Tenant ID
+
+    Identifier for the tenant to which the user belongs.
+    """
+
+    user_id: IDStr
+    """
+    User ID
+
+    Identifier for the user.
+    """
+
+    agent_id: IDStr
+    """
+    Agent ID
+
+    Identifier for the agent used by the user.
+    """
+
+    runner_id: IDStr
+    """
+    Runner ID
+
+    Identifier for the runner used by the AI.
+    """
+
+    time_zone: str
+    """
+    Time Zone
+
+    IANA Time Zone.
+    Specify in continent/city format.
+    Example: "Asia/Tokyo"
+    """
+
+    language: str
+    """
+    Language
+
+    ISO 639-1 code.
+    Example: "en" (English), "ja" (Japanese)
+    """
+
+    metadata: dict[str, Any] = Field(default_factory=lambda: {})
+    """Metadata"""

kiarina_llm-1.0.0/src/kiarina/llm/run_context/_registry.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from ._model import RunContext
+from .settings import settings_manager
+
+
+def create_run_context(
+    *,
+    app_author: str | None = None,
+    app_name: str | None = None,
+    tenant_id: str | None = None,
+    user_id: str | None = None,
+    agent_id: str | None = None,
+    runner_id: str | None = None,
+    time_zone: str | None = None,
+    language: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> RunContext:
+    """
+    Create RunContext
+    """
+    settings = settings_manager.settings
+
+    return RunContext(
+        app_author=app_author if app_author is not None else settings.app_author,
+        app_name=app_name if app_name is not None else settings.app_name,
+        tenant_id=tenant_id if tenant_id is not None else settings.tenant_id,
+        user_id=user_id if user_id is not None else settings.user_id,
+        agent_id=agent_id if agent_id is not None else settings.agent_id,
+        runner_id=runner_id if runner_id is not None else settings.runner_id,
+        time_zone=time_zone if time_zone is not None else settings.time_zone,
+        language=language if language is not None else settings.language,
+        metadata=metadata if metadata is not None else settings.metadata,
+    )

kiarina_llm-1.0.0/src/kiarina/llm/run_context/_types/fs_name.py

@@ -0,0 +1,52 @@
+from typing import Annotated
+
+from pydantic import AfterValidator, StringConstraints
+
+FS_NAME_PATTERN = r"^[A-Za-z0-9._ -]+$"
+"""
+File system name pattern
+
+Permit ASCII letters, dots, underscores, hyphens, and spaces.
+Detailed constraints are checked by validation functions.
+"""
+
+WINDOWS_RESERVED = {
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    *{f"com{i}" for i in range(1, 10)},
+    *{f"lpt{i}" for i in range(1, 10)},
+}
+"""
+Set of reserved names in Windows
+
+Uppercase and lowercase letters are ignored.
+"""
+
+
+def _validate_fs_name(v: str) -> str:
+    name = v.strip()
+
+    if name.lower() in WINDOWS_RESERVED:
+        raise ValueError(f"'{v}' is a reserved name on Windows")
+
+    # Prohibiting names beginning with a dot
+    if name.startswith("."):
+        raise ValueError(f"'{v}' cannot start with a dot")
+
+    # Prohibiting endings with a dot or space
+    if name.endswith(".") or name.endswith(" "):
+        raise ValueError(f"'{v}' cannot end with a dot or space")
+
+    return v
+
+
+FSName = Annotated[
+    str,
+    StringConstraints(min_length=1, pattern=FS_NAME_PATTERN),
+    AfterValidator(_validate_fs_name),
+]
+"""
+Filesystem Safe Name Type
+"""

kiarina_llm-1.0.0/src/kiarina/llm/run_context/_types/id_str.py

@@ -0,0 +1,15 @@
+from typing import Annotated
+
+from pydantic import StringConstraints
+
+ID_PATTERN = r"^[a-zA-Z0-9._-]+$"
+"""
+Permitted ID patterns
+
+Alphanumeric characters, dot, underscore, hyphen, one character or more.
+"""
+
+IDStr = Annotated[str, StringConstraints(min_length=1, pattern=ID_PATTERN)]
+"""
+ID String type
+"""

kiarina_llm-1.0.0/src/kiarina/llm/run_context/settings.py

@@ -0,0 +1,80 @@
+import platform
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class RunContextSettings(BaseSettings):
+    """
+    Run Context Settings
+    """
+
+    model_config = SettingsConfigDict(env_prefix="KIARINA_LLM_RUN_CONTEXT_")
+
+    app_author: str = "kiarina"
+    """
+    Default value for the application author.
+
+    Alphanumeric characters, dots, underscores, hyphens, and spaces are allowed.
+    Leading and trailing dots, as well as spaces, are not allowed.
+    """
+
+    app_name: str = "kiarina-llm"
+    """
+    Default value for the application name.
+
+    Alphanumeric characters, dots, underscores, hyphens, and spaces are allowed.
+    Leading and trailing dots, as well as spaces, are not allowed.
+    """
+
+    tenant_id: str = ""
+    """
+    Default value for the tenant ID.
+
+    Alphanumeric characters, underscores, and hyphens are allowed.
+    """
+
+    user_id: str = ""
+    """
+    Default value for the user ID.
+
+    Alphanumeric characters, underscores, and hyphens are allowed.
+    """
+
+    agent_id: str = ""
+    """
+    Default value for the agent ID.
+
+    Alphanumeric characters, underscores, and hyphens are allowed.
+    """
+
+    runner_id: str = Field(default_factory=lambda: platform.system().lower())
+    """
+    Default value for the runner ID.
+
+    Alphanumeric characters, underscores, and hyphens are allowed.
+    """
+
+    time_zone: str = "UTC"
+    """
+    Default value for the time zone.
+
+    IANA time zone names are used.
+    Example: "Asia/Tokyo"
+    """
+
+    language: str = "en"
+    """
+    Default value for the language.
+
+    ISO 639-1 codes are used.
+    Example: "ja"
+    """
+
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    """Default value for the metadata."""
+
+
+settings_manager = SettingsManager(RunContextSettings)

kiarina_llm-1.0.0/tests/run_context/conftest.py

@@ -0,0 +1,12 @@
+import pytest
+
+from kiarina.llm.run_context import settings_manager
+
+
+@pytest.fixture(scope="session", autouse=True)
+def setup_settings():
+    settings_manager.user_config = {
+        "tenant_id": "test-tenant",
+        "user_id": "test-user",
+        "agent_id": "test-agent",
+    }

kiarina_llm-1.0.0/tests/run_context/test_create_run_context.py

@@ -0,0 +1,39 @@
+from kiarina.llm.run_context import create_run_context, settings_manager
+
+
+def test_create_run_context_with_settings():
+    """Test that RunContext is created using configuration values"""
+    context = create_run_context()
+    settings = settings_manager.settings
+    assert context.app_author == settings.app_author
+    assert context.app_name == settings.app_name
+    assert context.tenant_id == settings.tenant_id
+    assert context.user_id == settings.user_id
+    assert context.time_zone == settings.time_zone
+    assert context.language == settings.language
+    assert context.metadata == settings.metadata
+
+
+def test_create_run_context_with_overrides():
+    """Test that RunContext is created with argument overrides"""
+    context = create_run_context(
+        app_author="TestCompany",
+        app_name="TestApp",
+        tenant_id="tenant-123",
+        user_id="user-456",
+        agent_id="agent-789",
+        runner_id="test-runner",
+        time_zone="Asia/Tokyo",
+        language="ja",
+        metadata={"version": "1.0.0"},
+    )
+
+    assert context.app_author == "TestCompany"
+    assert context.app_name == "TestApp"
+    assert context.tenant_id == "tenant-123"
+    assert context.user_id == "user-456"
+    assert context.agent_id == "agent-789"
+    assert context.runner_id == "test-runner"
+    assert context.time_zone == "Asia/Tokyo"
+    assert context.language == "ja"
+    assert context.metadata == {"version": "1.0.0"}

kiarina_llm-1.0.0/tests/run_context/test_fs_name.py

@@ -0,0 +1,87 @@
+import pytest
+
+from kiarina.llm.run_context import create_run_context
+
+
+# fmt: off
+@pytest.mark.parametrize("name", [
+    "MyApp",
+    "My App",
+    "My-App",
+    "My_App",
+    "My.App",
+    "My App v1.0",
+    "Test-App_v2.1",
+    "Test App ",  # Trailing space is stripped, so this becomes valid
+    "Test ",      # Trailing space is stripped, so this becomes valid
+])
+# fmt: on
+def test_fs_name_valid(name):
+    """Test that valid FSName values are accepted"""
+    context = create_run_context(app_author=name, app_name=name)
+    assert context.app_author == name
+    assert context.app_name == name
+
+
+# fmt: off
+@pytest.mark.parametrize("name,expected_match", [
+    # Names ending with dots (spaces are stripped, so they're actually valid)
+    ("Test App.", "cannot end with a dot or space"),
+    ("Test.", "cannot end with a dot or space"),
+
+    # Names starting with dots
+    (".hidden", "cannot start with a dot"),
+    (".test", "cannot start with a dot"),
+    (".myapp", "cannot start with a dot"),
+
+    # Windows reserved names
+    ("CON", "is a reserved name on Windows"),
+    ("con", "is a reserved name on Windows"),
+    ("Con", "is a reserved name on Windows"),
+    ("PRN", "is a reserved name on Windows"),
+    ("prn", "is a reserved name on Windows"),
+    ("Prn", "is a reserved name on Windows"),
+    ("AUX", "is a reserved name on Windows"),
+    ("aux", "is a reserved name on Windows"),
+    ("Aux", "is a reserved name on Windows"),
+    ("NUL", "is a reserved name on Windows"),
+    ("nul", "is a reserved name on Windows"),
+    ("Nul", "is a reserved name on Windows"),
+    ("COM1", "is a reserved name on Windows"),
+    ("com1", "is a reserved name on Windows"),
+    ("Com1", "is a reserved name on Windows"),
+    ("COM9", "is a reserved name on Windows"),
+    ("com9", "is a reserved name on Windows"),
+    ("Com9", "is a reserved name on Windows"),
+    ("LPT1", "is a reserved name on Windows"),
+    ("lpt1", "is a reserved name on Windows"),
+    ("Lpt1", "is a reserved name on Windows"),
+    ("LPT9", "is a reserved name on Windows"),
+    ("lpt9", "is a reserved name on Windows"),
+    ("Lpt9", "is a reserved name on Windows"),
+
+    # Empty string
+    ("", None),  # No specific match pattern for empty string
+
+    # Invalid characters
+    ("Test/App", None),
+    ("Test\\App", None),
+    ("Test:App", None),
+    ("Test*App", None),
+    ("Test?App", None),
+    ("Test\"App", None),
+    ("Test<App", None),
+    ("Test>App", None),
+    ("Test|App", None),
+    ("Test@App", None),
+    ("Test#App", None),
+])
+# fmt: on
+def test_fs_name_invalid(name, expected_match):
+    """Test that invalid FSName values are rejected"""
+    if expected_match:
+        with pytest.raises(ValueError, match=expected_match):
+            create_run_context(app_author=name)
+    else:
+        with pytest.raises(ValueError):
+            create_run_context(app_author=name)

kiarina_llm-1.0.0/tests/run_context/test_id_str.py

@@ -0,0 +1,73 @@
+import pytest
+
+from kiarina.llm.run_context import create_run_context
+
+
+@pytest.mark.parametrize(
+    "id_str",
+    [
+        "simple",
+        "with-hyphen",
+        "with_underscore",
+        "with.dot",
+        "mixed-id_v1.0",
+        "123",
+        "id123",
+        "a",
+        "A",
+        "ID-123_v2.0",
+        "tenant.123",
+        "user.456",
+        "agent.v1.0",
+        "runner.test",
+        "tenant-123",
+        "user_456",
+        "agent-v1_0",
+        "runner_test-1",
+    ],
+)
+def test_id_str_valid(id_str):
+    """Test that valid IDStr values are accepted"""
+    context = create_run_context(
+        tenant_id=id_str,
+        user_id=id_str,
+        agent_id=id_str,
+        runner_id=id_str,
+    )
+    assert context.tenant_id == id_str
+    assert context.user_id == id_str
+    assert context.agent_id == id_str
+    assert context.runner_id == id_str
+
+
+@pytest.mark.parametrize(
+    "id_str",
+    [
+        "",  # Empty string
+        "id@domain",
+        "id with space",
+        "id/path",
+        "id\\path",
+        "id:port",
+        "id*wildcard",
+        "id?query",
+        'id"quote',
+        "id<bracket",
+        "id>bracket",
+        "id|pipe",
+        "id#hash",
+        "id%percent",
+        "id&ampersand",
+        "id+plus",
+        "id=equals",
+        "id[bracket]",
+        "id{brace}",
+        "id(paren)",
+        "id,comma",
+        "id;semicolon",
+    ],
+)
+def test_id_str_invalid(id_str):
+    """Test that invalid IDStr values are rejected"""
+    with pytest.raises(ValueError):
+        create_run_context(tenant_id=id_str)

kiarina_llm-1.0.0/tests/run_context/test_run_context.py

@@ -0,0 +1,36 @@
+import pytest
+
+from kiarina.llm.run_context import RunContext
+
+
+def test_valid():
+    data = {
+        "app_author": "TestCompany",
+        "app_name": "TestApp",
+        "tenant_id": "tenant-123",
+        "user_id": "user-456",
+        "agent_id": "agent-789",
+        "runner_id": "runner-001",
+        "time_zone": "UTC",
+        "language": "en",
+        "metadata": {"key": "value"},
+    }
+
+    run_context = RunContext.model_validate(data)
+    assert run_context.model_dump() == data
+
+
+def test_invalid():
+    with pytest.raises(Exception):
+        RunContext.model_validate(
+            {
+                "app_author": "Invalid/Name",  # Invalid character
+                "app_name": "TestApp",
+                "tenant_id": "tenant-123",
+                "user_id": "user-456",
+                "agent_id": "agent-789",
+                "runner_id": "runner-001",
+                "time_zone": "UTC",
+                "language": "en",
+            }
+        )