feat: implement company template system with 7 built-in presets

.pre-commit-config.yaml

@@ -14,6 +14,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        exclude: ^src/ai_company/templates/builtins/
       - id: check-toml
       - id: check-json
       - id: check-merge-conflict

pyproject.toml

@@ -13,6 +13,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
+    "jinja2==3.1.6",
     "pydantic==2.12.5",
     "pyyaml==6.0.2",
     "structlog==25.5.0",

src/ai_company/config/loader.py

@@ -1,6 +1,5 @@
 """YAML configuration loader with layered merging and validation."""
 
-import copy
 import logging
 import os
 import re
@@ -18,6 +17,7 @@
     ConfigValidationError,
 )
 from ai_company.config.schema import RootConfig
+from ai_company.config.utils import deep_merge
 
 logger = logging.getLogger(__name__)
 
@@ -35,33 +35,6 @@
 # ---------------------------------------------------------------------------
 
 
-def _deep_merge(
-    base: dict[str, Any],
-    override: dict[str, Any],
-) -> dict[str, Any]:
-    """Recursively merge *override* into *base*, returning a new dict.
-
-    Nested dicts are merged recursively.  Lists, scalars, and all other
-    types in *override* replace the corresponding value in *base*
-    entirely.  Keys present only in *base* are preserved unchanged in
-    the result.  Neither input dict is mutated.
-
-    Args:
-        base: Base configuration dict.
-        override: Override values to layer on top.
-
-    Returns:
-        A new merged dict.
-    """
-    result = copy.deepcopy(base)
-    for key, value in override.items():
-        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
-            result[key] = _deep_merge(result[key], value)
-        else:
-            result[key] = copy.deepcopy(value)
-    return result
-
-
 def _read_config_text(file_path: Path) -> str:
     """Read a configuration file as UTF-8 text.
 
@@ -214,10 +187,11 @@ def _build_line_map(yaml_text: str) -> dict[str, tuple[int, int]]:
     """
     try:
         root = yaml.compose(yaml_text, Loader=yaml.SafeLoader)
-    except yaml.YAMLError:
+    except yaml.YAMLError as exc:
         logger.warning(
             "Failed to compose YAML AST for line mapping; "
-            "validation errors will lack line/column information",
+            "validation errors will lack line/column information: %s",
+            exc,
         )
         return {}
     if root is None or not isinstance(root, yaml.MappingNode):
@@ -446,12 +420,12 @@ def load_config(
     #    and line-map construction)
     yaml_text = _read_config_text(config_path)
     primary = _parse_yaml_string(yaml_text, str(config_path))
-    merged = _deep_merge(merged, primary)
+    merged = deep_merge(merged, primary)
 
     # 3. Apply override layers
     for override_path in override_paths:
         override = _parse_yaml_file(Path(override_path))
-        merged = _deep_merge(merged, override)
+        merged = deep_merge(merged, override)
 
     # 4. Substitute environment variables on the fully merged config.
     # Use a neutral label so env-var errors aren't misattributed solely
@@ -491,7 +465,7 @@ def load_config_from_string(
         ConfigValidationError: If the merged config fails validation.
     """
     data = _parse_yaml_string(yaml_string, source_name)
-    merged = _deep_merge(default_config_dict(), data)
+    merged = deep_merge(default_config_dict(), data)
     merged = _substitute_env_vars(merged, source_file=source_name)
     line_map = _build_line_map(yaml_string)
     return _validate_config_dict(

src/ai_company/config/utils.py

@@ -0,0 +1,54 @@
+"""Shared configuration utilities."""
+
+import copy
+from typing import Any
+
+
+def to_float(value: Any, *, field_name: str = "value") -> float:
+    """Coerce a value to float with clear error reporting.
+
+    Args:
+        value: Value to convert (str, int, float, etc.).
+        field_name: Field name for error messages.
+
+    Returns:
+        Float value.
+
+    Raises:
+        ValueError: If *value* cannot be converted to float.
+    """
+    if value is None:
+        msg = f"Expected numeric value for {field_name}, got None"
+        raise ValueError(msg)
+    try:
+        return float(value)
+    except (TypeError, ValueError) as exc:
+        msg = f"Invalid numeric value for {field_name}: {value!r}"
+        raise ValueError(msg) from exc
+
+
+def deep_merge(
+    base: dict[str, Any],
+    override: dict[str, Any],
+) -> dict[str, Any]:
+    """Recursively merge *override* into *base*, returning a new dict.
+
+    Nested dicts are merged recursively.  Lists, scalars, and all other
+    types in *override* replace the corresponding value in *base*
+    entirely.  Keys present only in *base* are preserved unchanged in
+    the result.  Neither input dict is mutated.
+
+    Args:
+        base: Base configuration dict.
+        override: Override values to layer on top.
+
+    Returns:
+        A new merged dict.
+    """
+    result = copy.deepcopy(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+    return result

src/ai_company/templates/__init__.py

@@ -0,0 +1,64 @@
+"""Company templates: built-in presets and custom template loading.
+
+Public API
+----------
+.. autosummary::
+    load_template
+    load_template_file
+    list_templates
+    list_builtin_templates
+    render_template
+    CompanyTemplate
+    LoadedTemplate
+    TemplateInfo
+    TemplateMetadata
+    TemplateVariable
+    TemplateAgentConfig
+    TemplateDepartmentConfig
+    TemplateError
+    TemplateNotFoundError
+    TemplateRenderError
+    TemplateValidationError
+"""
+
+from ai_company.templates.errors import (
+    TemplateError,
+    TemplateNotFoundError,
+    TemplateRenderError,
+    TemplateValidationError,
+)
+from ai_company.templates.loader import (
+    LoadedTemplate,
+    TemplateInfo,
+    list_builtin_templates,
+    list_templates,
+    load_template,
+    load_template_file,
+)
+from ai_company.templates.renderer import render_template
+from ai_company.templates.schema import (
+    CompanyTemplate,
+    TemplateAgentConfig,
+    TemplateDepartmentConfig,
+    TemplateMetadata,
+    TemplateVariable,
+)
+
+__all__ = [
+    "CompanyTemplate",
+    "LoadedTemplate",
+    "TemplateAgentConfig",
+    "TemplateDepartmentConfig",
+    "TemplateError",
+    "TemplateInfo",
+    "TemplateMetadata",
+    "TemplateNotFoundError",
+    "TemplateRenderError",
+    "TemplateValidationError",
+    "TemplateVariable",
+    "list_builtin_templates",
+    "list_templates",
+    "load_template",
+    "load_template_file",
+    "render_template",
+]

src/ai_company/templates/builtins/agency.yaml

@@ -0,0 +1,52 @@
+template:
+  name: "Agency"
+  description: "Client-focused agency with project management and creative roles"
+  version: "1.0.0"
+  tags:
+    - "agency"
+    - "client-work"
+    - "creative"
+
+  variables:
+    - name: "company_name"
+      description: "Name of your agency"
+      default: "Creative Agency"
+    - name: "budget"
+      description: "Monthly budget in USD"
+      var_type: "float"
+      default: 100.0
+
+  company:
+    type: "agency"
+    budget_monthly: {{ budget | default(100.0) }}
+    autonomy: 0.5
+
+  departments:
+    - name: "operations"
+      budget_percent: 30
+      head_role: "Project Manager"
+    - name: "engineering"
+      budget_percent: 40
+      head_role: "Full-Stack Developer"
+    - name: "design"
+      budget_percent: 30
+      head_role: "UI Designer"
+
+  agents:
+    - role: "Project Manager"
+      level: "senior"
+      model: "sonnet"
+      personality_preset: "visionary_leader"
+      department: "operations"
+    - role: "UI Designer"
+      level: "mid"
+      model: "sonnet"
+      department: "design"
+    - role: "Full-Stack Developer"
+      level: "senior"
+      model: "sonnet"
+      personality_preset: "pragmatic_builder"
+      department: "engineering"
+
+  workflow: "kanban"
+  communication: "hybrid"

src/ai_company/templates/builtins/dev_shop.yaml

@@ -0,0 +1,63 @@
+template:
+  name: "Dev Shop"
+  description: "Software development focused team with QA and DevOps"
+  version: "1.0.0"
+  tags:
+    - "development"
+    - "engineering"
+    - "qa"
+
+  variables:
+    - name: "company_name"
+      description: "Name of your company"
+      default: "Dev Shop"
+    - name: "budget"
+      description: "Monthly budget in USD"
+      var_type: "float"
+      default: 75.0
+
+  company:
+    type: "dev_shop"
+    budget_monthly: {{ budget | default(75.0) }}
+    autonomy: 0.5
+
+  departments:
+    - name: "engineering"
+      budget_percent: 70
+      head_role: "Software Architect"
+    - name: "quality_assurance"
+      budget_percent: 20
+      head_role: "QA Lead"
+    - name: "operations"
+      budget_percent: 10
+      head_role: "DevOps/SRE Engineer"
+
+  agents:
+    - role: "Software Architect"
+      level: "principal"
+      model: "opus"
+      personality_preset: "methodical_analyst"
+      department: "engineering"
+    - role: "Backend Developer"
+      level: "senior"
+      model: "sonnet"
+      personality_preset: "pragmatic_builder"
+      department: "engineering"
+    - role: "Backend Developer"
+      level: "mid"
+      model: "haiku"
+      personality_preset: "eager_learner"
+      department: "engineering"
+    - role: "QA Lead"
+      level: "lead"
+      model: "sonnet"
+      personality_preset: "methodical_analyst"
+      department: "quality_assurance"
+    - role: "DevOps/SRE Engineer"
+      level: "mid"
+      model: "sonnet"
+      personality_preset: "pragmatic_builder"
+      department: "operations"
+
+  workflow: "agile_kanban"
+  communication: "hybrid"