julee 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

julee/docs/sphinx_hcd/utils.py

@@ -0,0 +1,180 @@
+"""Shared utilities for sphinx_hcd extension.
+
+Common functions used across multiple extension modules.
+"""
+
+import re
+from docutils import nodes
+
+
+def normalize_name(name: str) -> str:
+    """Normalize a name for comparison (lowercase, hyphens to spaces).
+
+    Args:
+        name: Name to normalize
+
+    Returns:
+        Normalized lowercase name with consistent spacing
+    """
+    return name.lower().replace("-", " ").replace("_", " ").strip()
+
+
+def slugify(text: str) -> str:
+    """Create a URL-safe slug from text.
+
+    Args:
+        text: Text to slugify
+
+    Returns:
+        URL-safe slug string
+    """
+    slug = text.lower()
+    slug = re.sub(r'[^a-z0-9\s-]', '', slug)
+    slug = re.sub(r'[\s_]+', '-', slug)
+    slug = re.sub(r'-+', '-', slug)
+    return slug.strip('-')
+
+
+def kebab_to_snake(name: str) -> str:
+    """Convert kebab-case to snake_case for Python module names.
+
+    Args:
+        name: Kebab-case name (e.g., 'audit-analysis')
+
+    Returns:
+        Snake_case name (e.g., 'audit_analysis')
+    """
+    return name.replace("-", "_")
+
+
+def parse_list_option(value: str) -> list[str]:
+    """Parse a newline-separated list option with optional bullet prefixes.
+
+    Handles RST-style lists like:
+        - First item
+        - Second item with (commas, inside)
+
+    Does NOT split on commas to preserve items containing parenthetical lists.
+
+    Args:
+        value: Raw option string
+
+    Returns:
+        List of stripped item strings
+    """
+    if not value:
+        return []
+    items = []
+    for line in value.strip().split('\n'):
+        item = line.strip().lstrip('- ')
+        if item:
+            items.append(item)
+    return items
+
+
+def parse_csv_option(value: str) -> list[str]:
+    """Parse a comma-separated list option.
+
+    Args:
+        value: Raw option string
+
+    Returns:
+        List of stripped item strings
+    """
+    if not value:
+        return []
+    return [item.strip() for item in value.split(',') if item.strip()]
+
+
+def parse_integration_options(value: str) -> list[dict]:
+    """Parse integration options with optional descriptions.
+
+    Supports format: integration-slug (description of data)
+    Example: pilot-data-collection (CMA documents, audit reports)
+
+    Args:
+        value: Raw option string
+
+    Returns:
+        List of dicts with 'slug' and 'description' keys
+    """
+    if not value:
+        return []
+
+    items = []
+    for line in value.strip().split('\n'):
+        line = line.strip().lstrip('- ')
+        if not line:
+            continue
+
+        # Parse: slug (description) or just slug
+        match = re.match(r'^([a-z0-9-]+)\s*(?:\(([^)]+)\))?$', line.strip())
+        if match:
+            items.append({
+                'slug': match.group(1),
+                'description': match.group(2).strip() if match.group(2) else None,
+            })
+        else:
+            # Fallback: treat whole line as slug
+            items.append({
+                'slug': line.strip(),
+                'description': None,
+            })
+
+    return items
+
+
+def path_to_root(docname: str) -> str:
+    """Calculate relative path from a document to the docs root.
+
+    Args:
+        docname: Document name (e.g., 'users/journeys/build-vocabulary')
+
+    Returns:
+        Relative path prefix (e.g., '../../')
+    """
+    depth = docname.count("/")
+    return "../" * depth
+
+
+def make_reference(uri: str, text: str, is_code: bool = False) -> nodes.reference:
+    """Create a reference node.
+
+    Args:
+        uri: Target URI
+        text: Link text
+        is_code: If True, render text as code/literal
+
+    Returns:
+        docutils reference node
+    """
+    ref = nodes.reference("", "", refuri=uri)
+    if is_code:
+        ref += nodes.literal(text=text)
+    else:
+        ref += nodes.Text(text)
+    return ref
+
+
+def make_internal_link(
+    docname: str,
+    target_doc: str,
+    text: str,
+    anchor: str | None = None,
+) -> nodes.reference:
+    """Create an internal document link with proper relative path.
+
+    Args:
+        docname: Current document name
+        target_doc: Target document path (e.g., 'applications/staff-portal')
+        text: Link text
+        anchor: Optional anchor within target page
+
+    Returns:
+        docutils reference node
+    """
+    prefix = path_to_root(docname)
+    uri = f"{prefix}{target_doc}.html"
+    if anchor:
+        uri = f"{uri}#{anchor}"
+    return make_reference(uri, text)

julee/domain/models/__init__.py

@@ -10,11 +10,6 @@ Re-exports commonly used models for convenient importing:
 """
 
 # Document models
-from .document import Document, DocumentStatus
-
-# Custom field types
-from .custom_fields.content_stream import ContentStream
-
 # Assembly models
 from .assembly import Assembly, AssemblyStatus
 from .assembly_specification import (
@@ -23,11 +18,15 @@ from .assembly_specification import (
     KnowledgeServiceQuery,
 )
 
+# Custom field types
+from .custom_fields.content_stream import ContentStream
+from .document import Document, DocumentStatus
+
 # Configuration models
 from .knowledge_service_config import KnowledgeServiceConfig
 
 # Policy models
-from .policy import Policy, PolicyStatus, DocumentPolicyValidation
+from .policy import DocumentPolicyValidation, Policy, PolicyStatus
 
 __all__ = [
     # Document models

julee/domain/models/assembly/assembly.py

@@ -12,11 +12,11 @@ All domain models use Pydantic BaseModel for validation, serialization,
 and type safety, following the patterns established in the sample project.
 """
 
-from pydantic import BaseModel, Field, field_validator
-from typing import Optional
 from datetime import datetime, timezone
 from enum import Enum
 
+from pydantic import BaseModel, Field, field_validator
+
 
 class AssemblyStatus(str, Enum):
     """Status of an assembly process."""
@@ -52,16 +52,16 @@ class Assembly(BaseModel):
 
     # Assembly process tracking
     status: AssemblyStatus = AssemblyStatus.PENDING
-    assembled_document_id: Optional[str] = Field(
+    assembled_document_id: str | None = Field(
         default=None,
         description="ID of the assembled document produced by this assembly",
     )
 
     # Assembly metadata
-    created_at: Optional[datetime] = Field(
+    created_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
-    updated_at: Optional[datetime] = Field(
+    updated_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
 
@@ -89,8 +89,8 @@ class Assembly(BaseModel):
     @field_validator("assembled_document_id")
     @classmethod
     def assembled_document_id_must_not_be_empty_if_provided(
-        cls, v: Optional[str]
-    ) -> Optional[str]:
+        cls, v: str | None
+    ) -> str | None:
         if v is not None and (not v or not v.strip()):
             raise ValueError("Assembled document ID cannot be empty string")
         return v.strip() if v else None

julee/domain/models/assembly/tests/factories.py

@@ -6,9 +6,10 @@ Assembly domain objects with sensible defaults.
 """
 
 from datetime import datetime, timezone
+
 from factory.base import Factory
-from factory.faker import Faker
 from factory.declarations import LazyFunction
+from factory.faker import Faker
 
 from julee.domain.models.assembly import (
     Assembly,

julee/domain/models/assembly/tests/test_assembly.py

@@ -19,11 +19,14 @@ Design decisions documented:
 - Timestamps are automatically set with timezone-aware defaults
 """
 
-import pytest
 import json
 from datetime import datetime, timezone
 
+import pytest
+from pydantic import ValidationError
+
 from julee.domain.models.assembly import Assembly, AssemblyStatus
+
 from .factories import AssemblyFactory
 
 
@@ -79,7 +82,7 @@ class TestAssemblyInstantiation:
             assert assembly.updated_at is not None
         else:
             # Should raise validation error
-            with pytest.raises(Exception):  # Could be ValueError or ValidationError
+            with pytest.raises((ValueError, ValidationError)):
                 Assembly(
                     assembly_id=assembly_id,
                     assembly_specification_id=assembly_specification_id,
@@ -222,7 +225,7 @@ class TestAssemblyFieldValidation:
         assert valid_assembly.assembly_id == "valid-id"
 
         # Invalid cases
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="",
                 assembly_specification_id="spec-id",
@@ -230,7 +233,7 @@ class TestAssemblyFieldValidation:
                 workflow_id="test-workflow-123",
             )
 
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="   ",
                 assembly_specification_id="spec-id",
@@ -250,7 +253,7 @@ class TestAssemblyFieldValidation:
         assert valid_assembly.assembly_specification_id == "valid-spec-id"
 
         # Invalid cases
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="",
@@ -258,7 +261,7 @@ class TestAssemblyFieldValidation:
                 workflow_id="test-workflow-123",
             )
 
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="   ",
@@ -278,7 +281,7 @@ class TestAssemblyFieldValidation:
         assert valid_assembly.input_document_id == "valid-doc-id"
 
         # Invalid cases
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",
@@ -286,7 +289,7 @@ class TestAssemblyFieldValidation:
                 workflow_id="test-workflow-123",
             )
 
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",
@@ -345,7 +348,7 @@ class TestAssemblyDocumentManagement:
         assert none_assembly.assembled_document_id is None
 
         # Invalid cases - empty string
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",
@@ -355,7 +358,7 @@ class TestAssemblyDocumentManagement:
             )
 
         # Invalid cases - whitespace only
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",
@@ -391,7 +394,7 @@ class TestAssemblyWorkflowIdValidation:
         assert valid_assembly.workflow_id == "valid-workflow-id"
 
         # Invalid cases - empty string
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",
@@ -400,7 +403,7 @@ class TestAssemblyWorkflowIdValidation:
             )
 
         # Invalid cases - whitespace only
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",
@@ -421,7 +424,7 @@ class TestAssemblyWorkflowIdValidation:
     def test_workflow_id_required(self) -> None:
         """Test that workflow_id is required."""
         # workflow_id is required and cannot be omitted
-        with pytest.raises(Exception):
+        with pytest.raises((ValueError, ValidationError)):
             Assembly(  # type: ignore[call-arg]
                 assembly_id="asm-id",
                 assembly_specification_id="spec-id",

julee/domain/models/assembly_specification/assembly_specification.py

@@ -13,12 +13,13 @@ All domain models use Pydantic BaseModel for validation, serialization,
 and type safety, following the patterns established in the sample project.
 """
 
-from pydantic import BaseModel, Field, field_validator
-from typing import Optional, Dict, Any
 from datetime import datetime, timezone
 from enum import Enum
-import jsonschema
+from typing import Any
+
 import jsonpointer  # type: ignore
+import jsonschema
+from pydantic import BaseModel, Field, field_validator
 
 
 class AssemblySpecificationStatus(str, Enum):
@@ -56,14 +57,14 @@ class AssemblySpecification(BaseModel):
         "service for document-assembly matching"
     )
 
-    jsonschema: Dict[str, Any] = Field(
+    jsonschema: dict[str, Any] = Field(
         description="JSON Schema defining the structure of data to be "
         "extracted for this assembly"
     )
 
     # AssemblySpecification configuration
     status: AssemblySpecificationStatus = AssemblySpecificationStatus.ACTIVE
-    knowledge_service_queries: Dict[str, str] = Field(
+    knowledge_service_queries: dict[str, str] = Field(
         default_factory=dict,
         description="Mapping from JSON Pointer paths to "
         "KnowledgeServiceQuery IDs. Keys are JSON Pointer strings "
@@ -73,10 +74,10 @@ class AssemblySpecification(BaseModel):
 
     # AssemblySpecification metadata
     version: str = Field(default="0.1.0", description="Assembly definition version")
-    created_at: Optional[datetime] = Field(
+    created_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
-    updated_at: Optional[datetime] = Field(
+    updated_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
     # May later add a detailed description, change log, additional metadata
@@ -105,7 +106,7 @@ class AssemblySpecification(BaseModel):
 
     @field_validator("jsonschema")
     @classmethod
-    def jsonschema_must_be_valid(cls, v: Dict[str, Any]) -> Dict[str, Any]:
+    def jsonschema_must_be_valid(cls, v: dict[str, Any]) -> dict[str, Any]:
         if not isinstance(v, dict):
             raise ValueError("JSON Schema must be a dictionary")
 
@@ -124,8 +125,8 @@ class AssemblySpecification(BaseModel):
     @field_validator("knowledge_service_queries")
     @classmethod
     def knowledge_service_queries_must_be_valid(
-        cls, v: Dict[str, str], info: Any
-    ) -> Dict[str, str]:
+        cls, v: dict[str, str], info: Any
+    ) -> dict[str, str]:
         if not isinstance(v, dict):
             raise ValueError("Knowledge service queries must be a dictionary")
 

julee/domain/models/assembly_specification/knowledge_service_query.py

@@ -15,9 +15,10 @@ All domain models use Pydantic BaseModel for validation, serialization,
 and type safety, following the patterns established in the sample project.
 """
 
-from pydantic import BaseModel, Field, field_validator
-from typing import Optional, Dict, Any
 from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
 
 
 class KnowledgeServiceQuery(BaseModel):
@@ -37,26 +38,30 @@ class KnowledgeServiceQuery(BaseModel):
 
     Examples of query_metadata usage:
 
-    For Anthropic services:
+    For Anthropic services::
+
         query_metadata = {
             "model": "claude-sonnet-4-20250514",
             "max_tokens": 4000,
             "temperature": 0.1
         }
 
-    For OpenAI services:
+    For OpenAI services::
+
         query_metadata = {
             "model": "gpt-4",
             "temperature": 0.2,
             "top_p": 0.9
         }
 
-    For custom services:
+    For custom services::
+
         query_metadata = {
             "endpoint": "custom-model-v2",
             "timeout": 30,
             "retries": 3
         }
+
     """
 
     # Core query identification
@@ -73,13 +78,13 @@ class KnowledgeServiceQuery(BaseModel):
     )
 
     # Service-specific configuration
-    query_metadata: Optional[Dict[str, Any]] = Field(
+    query_metadata: dict[str, Any] | None = Field(
         default_factory=dict,
         description="Service-specific metadata and configuration options "
         "such as model selection, temperature, max_tokens, etc. "
         "The structure depends on the specific knowledge service being used.",
     )
-    assistant_prompt: Optional[str] = Field(
+    assistant_prompt: str | None = Field(
         default=None,
         description="Optional assistant message content to constrain "
         "or prime the model's response. This is added as the final "
@@ -87,10 +92,10 @@ class KnowledgeServiceQuery(BaseModel):
         "allowing control over response format and structure.",
     )
 
-    created_at: Optional[datetime] = Field(
+    created_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
-    updated_at: Optional[datetime] = Field(
+    updated_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
 

julee/domain/models/assembly_specification/tests/factories.py

@@ -7,9 +7,10 @@ AssemblySpecification domain objects with sensible defaults.
 
 from datetime import datetime, timezone
 from typing import Any
+
 from factory.base import Factory
-from factory.faker import Faker
 from factory.declarations import LazyAttribute, LazyFunction
+from factory.faker import Faker
 
 from julee.domain.models.assembly_specification import (
     AssemblySpecification,

julee/domain/models/assembly_specification/tests/test_assembly_specification.py

@@ -18,14 +18,17 @@ Design decisions documented:
 - Status defaults to ACTIVE
 """
 
-import pytest
 import json
-from typing import Dict, Any
+from typing import Any
+
+import pytest
+from pydantic import ValidationError
 
 from julee.domain.models.assembly_specification import (
     AssemblySpecification,
     AssemblySpecificationStatus,
 )
+
 from .factories import AssemblyFactory
 
 
@@ -136,7 +139,7 @@ class TestAssemblyInstantiation:
         assembly_specification_id: str,
         name: str,
         applicability: str,
-        jsonschema: Dict[str, Any],
+        jsonschema: dict[str, Any],
         expected_success: bool,
     ) -> None:
         """Test assembly creation with various field validation scenarios."""
@@ -158,7 +161,7 @@ class TestAssemblyInstantiation:
             assert assembly.version == "0.1.0"  # Default
         else:
             # Should raise validation error
-            with pytest.raises(Exception):  # Could be ValueError or ValidationError
+            with pytest.raises((ValueError, ValidationError)):
                 AssemblySpecification(
                     assembly_specification_id=assembly_specification_id,
                     name=name,
@@ -213,7 +216,7 @@ class TestAssemblyKnowledgeServiceQueriesValidation:
             assert assembly.knowledge_service_queries == knowledge_service_queries
         else:
             # Should raise validation error
-            with pytest.raises(Exception):
+            with pytest.raises((ValueError, ValidationError)):
                 AssemblySpecification(
                     assembly_specification_id="test-id",
                     name="Test Assembly",
@@ -486,5 +489,5 @@ class TestAssemblyVersionValidation:
             assembly = AssemblyFactory.build(version=version)
             assert assembly.version == version.strip()
         else:
-            with pytest.raises(Exception):
+            with pytest.raises((ValueError, ValidationError)):
                 AssemblyFactory.build(version=version)

julee/domain/models/assembly_specification/tests/test_knowledge_service_query.py

@@ -19,10 +19,12 @@ Design decisions documented:
 """
 
 import pytest
+from pydantic import ValidationError
 
 from julee.domain.models.assembly_specification import (
     KnowledgeServiceQuery,
 )
+
 from .factories import KnowledgeServiceQueryFactory
 
 
@@ -137,7 +139,7 @@ class TestKnowledgeServiceQueryInstantiation:
             assert query.prompt == prompt.strip()
         else:
             # Should raise validation error
-            with pytest.raises(Exception):  # Could be ValueError or ValidationError
+            with pytest.raises((ValueError, ValidationError)):
                 KnowledgeServiceQuery(
                     query_id=query_id,
                     name=name,

julee/domain/models/custom_fields/content_stream.py

@@ -6,10 +6,11 @@ validation
 for specialized data types used in the document processing workflow.
 """
 
+import io
+from typing import Any
+
 from pydantic import GetCoreSchemaHandler
 from pydantic_core import core_schema
-from typing import Any
-import io
 
 
 class ContentStream:

julee/domain/models/custom_fields/tests/test_custom_fields.py

@@ -12,10 +12,11 @@ Design decisions documented:
 - ContentStream works with Pydantic validation without arbitrary_types_allowed
 """
 
-import pytest
 import io
 from typing import Any
 
+import pytest
+
 from julee.domain.models.custom_fields.content_stream import (
     ContentStream,
 )