universal-agent-context 0.2.0__py3-none-any.whl

uacs/skills_validator.py

@@ -0,0 +1,367 @@
+"""Agent Skills SKILL.md validator based on agentskills.io specification.
+
+Validates SKILL.md files against the official Agent Skills format specification:
+- YAML frontmatter validation
+- Required fields: name, description
+- Allowed fields: name, description, license, allowed-tools, metadata, compatibility
+- Name constraints: kebab-case, max 64 chars, no leading/trailing hyphens
+- Description: max 1024 chars
+- Compatibility: max 500 chars
+- Directory name must match skill name
+"""
+
+import re
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar
+
+import yaml
+
+
+@dataclass
+class ValidationError:
+    """A single validation error."""
+
+    field: str
+    message: str
+    line: int | None = None
+
+
+@dataclass
+class ValidationResult:
+    """Result of validating a SKILL.md file."""
+
+    valid: bool
+    errors: list[ValidationError]
+    warnings: list[ValidationError]
+    metadata: dict[str, Any] | None = None
+
+
+class SkillValidator:
+    """Validates Agent Skills SKILL.md files against specification.
+
+    See https://agentskills.io/specification for full format specification.
+    """
+
+    # Field constraints from spec
+    MAX_NAME_LENGTH: ClassVar[int] = 64
+    MAX_DESCRIPTION_LENGTH: ClassVar[int] = 1024
+    MAX_COMPATIBILITY_LENGTH: ClassVar[int] = 500
+
+    # Allowed frontmatter fields
+    ALLOWED_FIELDS: ClassVar[set[str]] = {
+        "name",
+        "description",
+        "license",
+        "allowed-tools",
+        "metadata",
+        "compatibility",
+    }
+
+    # Required fields
+    REQUIRED_FIELDS: ClassVar[set[str]] = {"name", "description"}
+
+    # Name pattern: lowercase letters, numbers, hyphens only
+    # Must not start or end with hyphen
+    NAME_PATTERN: ClassVar[re.Pattern] = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+
+    @staticmethod
+    def normalize_unicode(text: str) -> str:
+        """Normalize Unicode text to NFC form."""
+        return unicodedata.normalize("NFC", text)
+
+    @staticmethod
+    def validate_name(name: str) -> list[ValidationError]:
+        """Validate skill name against spec constraints.
+
+        Constraints:
+        - Max 64 characters
+        - Lowercase letters, numbers, and hyphens only
+        - Must not start or end with a hyphen
+        - No consecutive hyphens
+        - Unicode normalized (NFC)
+        """
+        errors = []
+
+        if not name:
+            errors.append(ValidationError("name", "Name is required"))
+            return errors
+
+        # Normalize Unicode
+        normalized = SkillValidator.normalize_unicode(name)
+        if name != normalized:
+            errors.append(
+                ValidationError(
+                    "name",
+                    f"Name must be Unicode normalized (NFC). "
+                    f"Got: {name!r}, expected: {normalized!r}",
+                )
+            )
+
+        # Length check
+        if len(name) > SkillValidator.MAX_NAME_LENGTH:
+            errors.append(
+                ValidationError(
+                    "name",
+                    f"Name exceeds maximum length of {SkillValidator.MAX_NAME_LENGTH} "
+                    "characters",
+                )
+            )
+
+        # Pattern check (kebab-case)
+        if not SkillValidator.NAME_PATTERN.match(name):
+            errors.append(
+                ValidationError(
+                    "name",
+                    "Name must contain only lowercase letters, numbers, and hyphens. "
+                    "Must not start or end with a hyphen.",
+                )
+            )
+
+        # Check for consecutive hyphens
+        if "--" in name:
+            errors.append(
+                ValidationError("name", "Name must not contain consecutive hyphens")
+            )
+
+        return errors
+
+    @staticmethod
+    def validate_description(description: str) -> list[ValidationError]:
+        """Validate skill description against spec constraints.
+
+        Constraints:
+        - Required
+        - Max 1024 characters
+        - Non-empty
+        """
+        errors = []
+
+        if not description:
+            errors.append(ValidationError("description", "Description is required"))
+            return errors
+
+        if not description.strip():
+            errors.append(
+                ValidationError("description", "Description must not be empty")
+            )
+
+        if len(description) > SkillValidator.MAX_DESCRIPTION_LENGTH:
+            errors.append(
+                ValidationError(
+                    "description",
+                    f"Description exceeds maximum length of "
+                    f"{SkillValidator.MAX_DESCRIPTION_LENGTH} characters",
+                )
+            )
+
+        return errors
+
+    @staticmethod
+    def validate_compatibility(compatibility: str | None) -> list[ValidationError]:
+        """Validate compatibility field against spec constraints.
+
+        Constraints:
+        - Optional
+        - Max 500 characters
+        """
+        errors = []
+
+        if (
+            compatibility
+            and len(compatibility) > SkillValidator.MAX_COMPATIBILITY_LENGTH
+        ):
+            errors.append(
+                ValidationError(
+                    "compatibility",
+                    f"Compatibility exceeds maximum length of "
+                    f"{SkillValidator.MAX_COMPATIBILITY_LENGTH} characters",
+                )
+            )
+
+        return errors
+
+    @staticmethod
+    def validate_frontmatter_fields(
+        frontmatter: dict[str, Any],
+    ) -> list[ValidationError]:
+        """Validate that only allowed fields are present in frontmatter."""
+        errors = []
+
+        extra_fields = set(frontmatter.keys()) - SkillValidator.ALLOWED_FIELDS
+        if extra_fields:
+            errors.append(
+                ValidationError(
+                    "frontmatter",
+                    f"Unexpected fields in frontmatter: "
+                    f"{', '.join(sorted(extra_fields))}. "
+                    f"Allowed fields: "
+                    f"{', '.join(sorted(SkillValidator.ALLOWED_FIELDS))}",
+                )
+            )
+        missing_fields = SkillValidator.REQUIRED_FIELDS - set(frontmatter.keys())
+        if missing_fields:
+            errors.append(
+                ValidationError(
+                    "frontmatter",
+                    f"Missing required fields: {', '.join(sorted(missing_fields))}",
+                )
+            )
+
+        return errors
+
+    @staticmethod
+    def validate_directory_name(
+        skill_path: Path, skill_name: str
+    ) -> list[ValidationError]:
+        """Validate that directory name matches skill name.
+
+        Directory name must match the skill name from frontmatter (kebab-case).
+        """
+        errors = []
+
+        dir_name = skill_path.name
+        if dir_name != skill_name:
+            errors.append(
+                ValidationError(
+                    "directory",
+                    f"Directory name '{dir_name}' does not match skill name '{skill_name}'",
+                )
+            )
+
+        return errors
+
+    @staticmethod
+    def extract_frontmatter(
+        content: str,
+    ) -> tuple[dict[str, Any] | None, str | None, list[ValidationError]]:
+        """Extract and parse YAML frontmatter from SKILL.md content.
+
+        Returns:
+            Tuple of (parsed_frontmatter, remaining_content, errors)
+        """
+        errors = []
+
+        # Check for YAML frontmatter markers
+        if not content.startswith("---\n"):
+            errors.append(
+                ValidationError(
+                    "frontmatter", "SKILL.md must start with YAML frontmatter (---)"
+                )
+            )
+            return None, content, errors
+
+        # Find end of frontmatter
+        lines = content.split("\n")
+        end_marker_idx = None
+        for i, line in enumerate(lines[1:], start=1):
+            if line.strip() == "---":
+                end_marker_idx = i
+                break
+
+        if end_marker_idx is None:
+            errors.append(
+                ValidationError(
+                    "frontmatter",
+                    "YAML frontmatter not properly closed (missing closing ---)",
+                )
+            )
+            return None, content, errors
+
+        # Extract frontmatter YAML
+        frontmatter_text = "\n".join(lines[1:end_marker_idx])
+
+        # Parse YAML
+        try:
+            frontmatter = yaml.safe_load(frontmatter_text)
+            if not isinstance(frontmatter, dict):
+                errors.append(
+                    ValidationError(
+                        "frontmatter",
+                        "Frontmatter must be a YAML mapping (key-value pairs)",
+                    )
+                )
+                return None, content, errors
+        except yaml.YAMLError as e:
+            errors.append(
+                ValidationError("frontmatter", f"Invalid YAML in frontmatter: {e}")
+            )
+            return None, content, errors
+
+        # Extract remaining content
+        remaining = "\n".join(lines[end_marker_idx + 1 :])
+
+        return frontmatter, remaining, errors
+
+    @staticmethod
+    def validate_file(skill_path: Path) -> ValidationResult:
+        """Validate a SKILL.md file at the given path.
+
+        Args:
+            skill_path: Path to directory containing SKILL.md
+
+        Returns:
+            ValidationResult with errors, warnings, and metadata
+        """
+        errors = []
+        warnings = []
+
+        # Check that SKILL.md exists
+        skill_file = skill_path / "SKILL.md"
+        if not skill_file.exists():
+            errors.append(
+                ValidationError("file", f"SKILL.md file not found in {skill_path}")
+            )
+            return ValidationResult(valid=False, errors=errors, warnings=warnings)
+
+        # Read file content
+        try:
+            content = skill_file.read_text(encoding="utf-8")
+        except Exception as e:
+            errors.append(ValidationError("file", f"Failed to read SKILL.md: {e}"))
+            return ValidationResult(valid=False, errors=errors, warnings=warnings)
+
+        # Extract and parse frontmatter
+        frontmatter, body, fm_errors = SkillValidator.extract_frontmatter(content)
+        errors.extend(fm_errors)
+
+        if not frontmatter:
+            return ValidationResult(valid=False, errors=errors, warnings=warnings)
+
+        # Validate frontmatter fields
+        errors.extend(SkillValidator.validate_frontmatter_fields(frontmatter))
+
+        # Validate individual fields
+        if "name" in frontmatter:
+            errors.extend(SkillValidator.validate_name(frontmatter["name"]))
+
+            # Validate directory name matches skill name
+            errors.extend(
+                SkillValidator.validate_directory_name(skill_path, frontmatter["name"])
+            )
+
+        if "description" in frontmatter:
+            errors.extend(
+                SkillValidator.validate_description(frontmatter["description"])
+            )
+
+        if "compatibility" in frontmatter:
+            errors.extend(
+                SkillValidator.validate_compatibility(frontmatter["compatibility"])
+            )
+
+        # Check for body content (warning if empty)
+        if body and not body.strip():
+            warnings.append(
+                ValidationError(
+                    "body", "SKILL.md body is empty. Consider adding instructions."
+                )
+            )
+
+        return ValidationResult(
+            valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings,
+            metadata=frontmatter if len(errors) == 0 else None,
+        )

uacs/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility functions for UACS."""
+
+from uacs.utils.paths import get_project_root
+
+__all__ = ["get_project_root"]

uacs/utils/paths.py

@@ -0,0 +1,24 @@
+"""Path utilities for UACS."""
+
+import os
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """Get the effective project root directory.
+
+    Prioritizes PWD environment variable to handle cases where the tool
+    is invoked via 'uv run --directory ...' which changes the process CWD.
+
+    Returns:
+        Path to the project root directory
+    """
+    # Check if PWD is set and valid
+    pwd = os.environ.get("PWD")
+    if pwd:
+        path = Path(pwd)
+        if path.exists() and path.is_dir():
+            return path
+
+    # Fallback to current working directory
+    return Path.cwd()

uacs/visualization/README.md

@@ -0,0 +1,132 @@
+# UACS Visualization Module
+
+This module provides real-time web-based visualization of UACS context graphs.
+
+## Structure
+
+```
+visualization/
+├── __init__.py           # Module exports
+├── visualization.py      # Terminal-based Rich visualizations
+├── web_server.py        # FastAPI web server for browser UI
+├── static/              # Static web assets
+│   └── index.html       # Single-page web application
+└── README.md           # This file
+```
+
+## Quick Start
+
+### From CLI
+
+```bash
+# Start MCP server with web UI
+uacs serve --with-ui
+
+# Custom port
+uacs serve --with-ui --ui-port 3000
+```
+
+### From Python
+
+```python
+from pathlib import Path
+from uacs.context.shared_context import SharedContextManager
+from uacs.visualization.web_server import VisualizationServer
+import uvicorn
+
+# Initialize
+manager = SharedContextManager(Path(".state/context"))
+viz_server = VisualizationServer(manager, host="localhost", port=8081)
+
+# Run server
+config = uvicorn.Config(viz_server.app, host="localhost", port=8081)
+server = uvicorn.Server(config)
+await server.serve()
+```
+
+## Components
+
+### Terminal Visualization (`visualization.py`)
+
+Rich-based terminal visualizations for CLI usage:
+- Context graph as tree structure
+- Token usage meters
+- Agent interaction flow
+- Live dashboard with auto-refresh
+
+### Web Visualization (`web_server.py`)
+
+FastAPI server providing:
+- REST API endpoints for context data
+- WebSocket support for real-time updates
+- Static file serving for web UI
+
+### Web UI (`static/index.html`)
+
+Single-page application with:
+- D3.js for interactive graphs
+- Chart.js for statistics
+- 5 visualization modes
+- Real-time WebSocket updates
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | Main visualization page |
+| `GET /api/graph` | Context graph data |
+| `GET /api/stats` | Token statistics |
+| `GET /api/topics` | Topic clusters |
+| `GET /api/deduplication` | Deduplication data |
+| `GET /api/quality` | Quality distribution |
+| `WS /ws` | WebSocket for real-time updates |
+| `GET /health` | Health check |
+
+## Visualization Modes
+
+1. **Conversation Flow** - Interactive D3.js force-directed graph
+2. **Token Dashboard** - Real-time token usage charts
+3. **Deduplication** - Duplicate content analysis
+4. **Quality Distribution** - Content quality metrics
+5. **Topic Clusters** - Topic network visualization
+
+## Documentation
+
+For complete documentation, see: [docs/VISUALIZATION.md](../../../docs/VISUALIZATION.md)
+
+## Testing
+
+```bash
+# Run tests
+pytest tests/test_visualization_server.py -v
+
+# Run demo
+python examples/visualization_demo.py
+```
+
+## Development
+
+### Adding New Endpoints
+
+1. Add method to `VisualizationServer._setup_routes()`
+2. Implement data processing method
+3. Add frontend update function in `index.html`
+
+### Modifying Visualizations
+
+Edit `static/index.html`:
+- CSS for styling (in `<style>` section)
+- JavaScript for behavior (in `<script>` section)
+- D3.js/Chart.js configuration for visualizations
+
+## Dependencies
+
+- FastAPI - Web framework
+- Uvicorn - ASGI server
+- WebSockets - Real-time communication
+- D3.js (CDN) - Graph visualization
+- Chart.js (CDN) - Statistical charts
+
+## License
+
+MIT License (same as UACS)

uacs/visualization/__init__.py

@@ -0,0 +1,36 @@
+"""Visualization module for UACS context graphs and trace visualization."""
+
+from uacs.visualization.visualization import ContextVisualizer
+from uacs.visualization.web_server import VisualizationServer, start_visualization_server
+from uacs.visualization.models import (
+    Event,
+    EventType,
+    Session,
+    SessionList,
+    EventList,
+    TokenAnalytics,
+    CompressionAnalytics,
+    TopicAnalytics,
+    SearchRequest,
+    SearchResults,
+    CompressionTrigger,
+)
+from uacs.visualization.storage import TraceStorage
+
+__all__ = [
+    "ContextVisualizer",
+    "VisualizationServer",
+    "start_visualization_server",
+    "Event",
+    "EventType",
+    "Session",
+    "SessionList",
+    "EventList",
+    "TokenAnalytics",
+    "CompressionAnalytics",
+    "TopicAnalytics",
+    "SearchRequest",
+    "SearchResults",
+    "CompressionTrigger",
+    "TraceStorage",
+]