# Familiar - Self-Hosted AI Agent Framework
# Copyright (c) 2026 George Scott Foley
# Licensed under the MIT License - see LICENSE file for details

"""
Guidance system for workflow-driven agent interactions.

Provides configurable guidance templates that direct agent behavior
for structured tasks (intake, troubleshooting, etc.)
"""

import logging
from dataclasses import dataclass
from typing import Any, Dict, List, Optional

logger = logging.getLogger(__name__)


@dataclass
class GuidanceConfig:
    """Configuration for the guidance system."""

    template_dir: str = "guidance_templates"
    default_template: str = "general"
    max_steps: int = 20
    allow_dynamic: bool = True


class GuidanceLoader:
    """Loads and manages guidance templates for structured workflows."""

    def __init__(self, config: Optional[GuidanceConfig] = None):
        self.config = config or GuidanceConfig()
        self._templates: Dict[str, Any] = {}
        logger.debug(f"GuidanceLoader initialized with config: {self.config}")

    def load_template(self, name: str) -> Optional[Dict]:
        """Load a guidance template by name."""
        return self._templates.get(name)

    def register_template(self, name: str, template: Dict) -> None:
        """Register a guidance template."""
        self._templates[name] = template

    def list_templates(self) -> List[str]:
        """List available template names."""
        return list(self._templates.keys())
