"""Lazy skill loading system for Oclawma.

This module provides the skill system for Oclawma, including:
- Skill manifest format (YAML)
- Skill class with lazy loading
- Skill registry that loads skills on-demand
- Token count caching
- Skill discovery from filesystem
- Entry point discovery for pip-installed skills
- Tool schema definitions

Example:
    >>> from oclawma.skills import SkillRegistry, SkillManifest
    >>>
    >>> # Discover skills from filesystem
    >>> registry = SkillRegistry()
    >>> registry.discover_skills("/path/to/skills")
    >>>
    >>> # Skills are not loaded yet - only discovered
    >>> print(f"Available skills: {registry.list_available()}")
    >>>
    >>> # Skill is loaded only when tool is invoked
    >>> result = await registry.execute_tool("docker", "ps")

Pip-Installed Skills:
    >>> from oclawma.skills import EntryPointDiscovery
    >>>
    >>> # Discover pip-installed skills
    >>> discovery = EntryPointDiscovery()
    >>> for skill_class, metadata in discovery.discover():
    ...     print(f"Found: {metadata.name}")
"""

from __future__ import annotations

# Base classes and exceptions
from oclawma.skills.base import (
    SkillError,
    SkillLoadError,
    SkillMetadata,
    SkillNotFoundError,
    SkillToolError,
    ToolInfo,
)

# Discovery from filesystem
from oclawma.skills.discovery import SkillDiscovery

# Entry point discovery for pip-installed skills
from oclawma.skills.entry_points import (
    SKILL_ENTRY_POINT_GROUP,
    EntryPointDiscovery,
    register_entry_point_skills,
)

# Manifest parsing
from oclawma.skills.manifest import ManifestParser, SkillManifest

# Registry with on-demand loading
from oclawma.skills.registry import SkillRegistry, create_registry

# Tool schema definitions
from oclawma.skills.schema import (
    ParameterType,
    ReturnType,
    SkillSchema,
    ToolExample,
    ToolParameter,
    ToolReturns,
    ToolSchema,
    create_tool_schema,
    from_function,
)

# Skill classes with lazy loading
from oclawma.skills.skill import (
    FunctionSkill,
    LazySkill,
    ManifestSkill,
    Skill,
)

# Token caching and budget tracking
from oclawma.skills.token_cache import (
    TokenBudgetTracker,
    TokenCache,
    TokenCacheEntry,
)

__all__ = [
    # Base classes
    "Skill",
    "LazySkill",
    "ManifestSkill",
    "FunctionSkill",
    # Manifest
    "SkillManifest",
    "ManifestParser",
    # Metadata
    "SkillMetadata",
    "ToolInfo",
    # Exceptions
    "SkillError",
    "SkillLoadError",
    "SkillNotFoundError",
    "SkillToolError",
    # Discovery
    "SkillDiscovery",
    # Entry points (pip-installed skills)
    "EntryPointDiscovery",
    "register_entry_point_skills",
    "SKILL_ENTRY_POINT_GROUP",
    # Tool schemas
    "ToolSchema",
    "ToolParameter",
    "ToolReturns",
    "ToolExample",
    "SkillSchema",
    "ParameterType",
    "ReturnType",
    "create_tool_schema",
    "from_function",
    # Caching
    "TokenCache",
    "TokenCacheEntry",
    "TokenBudgetTracker",
    # Registry
    "SkillRegistry",
    "create_registry",
]


def create_lazy_registry(skills_path: str | None = None) -> SkillRegistry:
    """Create a skill registry with lazy loading enabled.

    This is the recommended way to initialize the skill system.
    Skills are discovered but not loaded until their tools are invoked.

    Args:
        skills_path: Optional path to skills directory. If not provided,
                     uses the OCLAWMA_SKILLS_PATH env var or default location.

    Returns:
        Configured SkillRegistry with lazy loading
    """
    import os

    if skills_path is None:
        skills_path = os.environ.get("OCLAWMA_SKILLS_PATH", os.path.expanduser("~/.oclawma/skills"))

    registry = SkillRegistry()

    # Discover skills but don't load them yet
    if os.path.isdir(skills_path):
        registry.discover_skills(skills_path)

    return registry
