better-notion 1.5.5__tar.gz → 1.6.0__tar.gz

{better_notion-1.5.5 → better_notion-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better-notion
-Version: 1.5.5
+Version: 1.6.0
 Summary: A high-level Python SDK for the Notion API with developer experience in mind.
 Project-URL: Homepage, https://github.com/nesalia-inc/better-notion
 Project-URL: Documentation, https://github.com/nesalia-inc/better-notion#readme

better_notion-1.6.0/better_notion/_cli/docs/__init__.py

@@ -0,0 +1,20 @@
+"""Documentation system for AI agents.
+
+This module provides infrastructure for documenting CLI commands
+in a machine-readable format that AI agents can consume to understand
+the system at a high level of abstraction.
+"""
+
+from better_notion._cli.docs.base import (
+    Command,
+    Concept,
+    Schema,
+    Workflow,
+)
+
+__all__ = [
+    "Schema",
+    "Concept",
+    "Workflow",
+    "Command",
+]

better_notion-1.6.0/better_notion/_cli/docs/base.py

@@ -0,0 +1,204 @@
+"""Base classes for documentation system.
+
+This module provides the core data structures for documenting
+CLI commands and workflows in a machine-readable format.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Concept:
+    """A concept represents a high-level idea in the system.
+
+    Concepts help AI agents understand what things are
+    (e.g., "workspace", "task", "version") beyond just
+    command syntax.
+
+    Attributes:
+        name: Name of the concept
+        description: Human-readable description
+        properties: Dict of concept properties and their meanings
+        relationships: Relationships to other concepts
+    """
+
+    name: str
+    description: str
+    properties: dict[str, Any] = field(default_factory=dict)
+    relationships: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "properties": self.properties,
+            "relationships": self.relationships,
+        }
+
+
+@dataclass
+class WorkflowStep:
+    """A single step in a workflow.
+
+    Attributes:
+        description: What this step does
+        command: Optional command to execute
+        purpose: Why this step is needed
+    """
+
+    description: str
+    command: str | None = None
+    purpose: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "description": self.description,
+            "command": self.command,
+            "purpose": self.purpose,
+        }
+
+
+@dataclass
+class ErrorRecovery:
+    """Error recovery strategy for a command.
+
+    Attributes:
+        error_type: Type of error (e.g., "workspace_exists")
+        message: Human-readable error message
+        solutions: List of possible solutions with flags/actions
+    """
+
+    error_type: str
+    message: str
+    solutions: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "error_type": self.error_type,
+            "message": self.message,
+            "solutions": self.solutions,
+        }
+
+
+@dataclass
+class Workflow:
+    """A workflow represents a sequence of operations.
+
+    Workflows help AI agents understand how to accomplish
+    high-level goals (e.g., "initialize_workspace",
+    "create_task").
+
+    Attributes:
+        name: Workflow name
+        description: What this workflow accomplishes
+        steps: List of steps in the workflow
+        commands: Example commands for this workflow
+        prerequisites: Required conditions before starting
+        error_recovery: Error handling strategies
+    """
+
+    name: str
+    description: str
+    steps: list[WorkflowStep | dict[str, Any]] = field(default_factory=list)
+    commands: list[str] = field(default_factory=list)
+    prerequisites: list[str] = field(default_factory=list)
+    error_recovery: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "steps": [
+                step.to_dict() if isinstance(step, WorkflowStep) else step
+                for step in self.steps
+            ],
+            "commands": self.commands,
+            "prerequisites": self.prerequisites,
+            "error_recovery": self.error_recovery,
+        }
+
+
+@dataclass
+class Command:
+    """Documentation for a single command.
+
+    Command docs go beyond --help text to provide semantic
+    meaning and workflow context.
+
+    Attributes:
+        name: Command name
+        purpose: What this command does (semantic meaning)
+        description: Detailed description
+        flags: Dict of flag -> purpose
+        workflow: Which workflow this command belongs to
+        when_to_use: When this command should be used
+        error_recovery: Error handling strategies
+    """
+
+    name: str
+    purpose: str
+    description: str = ""
+    flags: dict[str, str] = field(default_factory=dict)
+    workflow: str | None = None
+    when_to_use: list[str] = field(default_factory=list)
+    error_recovery: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "purpose": self.purpose,
+            "description": self.description,
+            "flags": self.flags,
+            "workflow": self.workflow,
+            "when_to_use": self.when_to_use,
+            "error_recovery": self.error_recovery,
+        }
+
+
+@dataclass
+class Schema:
+    """Complete schema documentation for a plugin.
+
+    A Schema provides everything an AI agent needs to understand
+    a plugin system at a high level.
+
+    Attributes:
+        name: Plugin name
+        version: Schema version
+        description: Plugin description
+        concepts: High-level concepts in the system
+        workflows: Available workflows
+        commands: Command documentation
+        best_practices: Recommended usage patterns
+        examples: Usage examples
+    """
+
+    name: str
+    version: str
+    description: str
+    concepts: list[Concept] = field(default_factory=list)
+    workflows: list[Workflow] = field(default_factory=list)
+    commands: dict[str, Command] = field(default_factory=dict)
+    best_practices: list[str] = field(default_factory=list)
+    examples: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "concepts": [concept.to_dict() for concept in self.concepts],
+            "workflows": [workflow.to_dict() for workflow in self.workflows],
+            "commands": {
+                name: command.to_dict() for name, command in self.commands.items()
+            },
+            "best_practices": self.best_practices,
+            "examples": self.examples,
+        }

better_notion-1.6.0/better_notion/_cli/docs/formatters.py

@@ -0,0 +1,128 @@
+"""Formatters for schema documentation.
+
+This module provides utilities to format Schema objects
+into different output formats (JSON, YAML).
+"""
+
+import json
+from typing import Any
+
+from better_notion._cli.docs.base import Schema
+
+
+def format_schema_json(schema: Schema, *, pretty: bool = True) -> str:
+    """Format a Schema as JSON.
+
+    Args:
+        schema: Schema object to format
+        pretty: Whether to pretty-print with indentation
+
+    Returns:
+        JSON string representation of the schema
+    """
+    schema_dict = schema.to_dict()
+    if pretty:
+        return json.dumps(schema_dict, indent=2)
+    return json.dumps(schema_dict)
+
+
+def format_schema_yaml(schema: Schema) -> str:
+    """Format a Schema as YAML.
+
+    Args:
+        schema: Schema object to format
+
+    Returns:
+        YAML string representation of the schema
+    """
+    try:
+        import yaml
+
+        return yaml.dump(schema.to_dict(), default_flow_style=False)
+    except ImportError:
+        # Fall back to JSON if pyyaml not installed
+        logger = __import__("logging").getLogger(__name__)
+        logger.warning("PyYAML not installed, falling back to JSON")
+        return format_schema_json(schema)
+
+
+def format_schema_pretty(schema: Schema) -> str:
+    """Format a Schema as human-readable text with sections.
+
+    This provides a more readable format for human consumption
+    while maintaining machine-parsable structure.
+
+    Args:
+        schema: Schema object to format
+
+    Returns:
+        Formatted text string
+    """
+    lines = []
+    data = schema.to_dict()
+
+    # Header
+    lines.append(f"# {schema.name.upper()} SCHEMA")
+    lines.append(f"Version: {schema.version}")
+    lines.append(f"Description: {schema.description}")
+    lines.append("")
+
+    # Concepts
+    if data["concepts"]:
+        lines.append("## CONCEPTS")
+        for concept in data["concepts"]:
+            lines.append(f"### {concept['name']}")
+            lines.append(f"{concept['description']}")
+            if concept.get("properties"):
+                lines.append("**Properties:**")
+                for key, value in concept["properties"].items():
+                    lines.append(f"  - {key}: {value}")
+            if concept.get("relationships"):
+                lines.append("**Relationships:**")
+                for key, value in concept["relationships"].items():
+                    lines.append(f"  - {key}: {value}")
+            lines.append("")
+
+    # Workflows
+    if data["workflows"]:
+        lines.append("## WORKFLOWS")
+        for workflow in data["workflows"]:
+            lines.append(f"### {workflow['name']}")
+            lines.append(f"{workflow['description']}")
+            if workflow.get("steps"):
+                lines.append("**Steps:**")
+                for i, step in enumerate(workflow["steps"], 1):
+                    if isinstance(step, dict):
+                        lines.append(f"  {i}. {step.get('description', step)}")
+                    else:
+                        lines.append(f"  {i}. {step}")
+            if workflow.get("commands"):
+                lines.append("**Commands:**")
+                for cmd in workflow["commands"]:
+                    lines.append(f"  - {cmd}")
+            lines.append("")
+
+    # Commands
+    if data["commands"]:
+        lines.append("## COMMANDS")
+        for cmd_name, cmd in data["commands"].items():
+            lines.append(f"### {cmd_name}")
+            lines.append(f"**Purpose:** {cmd.get('purpose', 'N/A')}")
+            if cmd.get("flags"):
+                lines.append("**Flags:**")
+                for flag, purpose in cmd["flags"].items():
+                    lines.append(f"  - {flag}: {purpose}")
+            if cmd.get("when_to_use"):
+                lines.append("**When to use:**")
+                for usage in cmd["when_to_use"]:
+                    lines.append(f"  - {usage}")
+            lines.append("")
+
+    # Best Practices
+    if data.get("best_practices"):
+        lines.append("## BEST PRACTICES")
+        for practice in data["best_practices"]:
+            lines.append(f"- {practice}")
+        lines.append("")
+
+    return "\n".join(lines)

better_notion-1.6.0/better_notion/_cli/docs/registry.py

@@ -0,0 +1,82 @@
+"""Schema registry for plugin documentation.
+
+This module provides a central registry where plugins can register
+their documentation schemas for AI agent consumption.
+"""
+
+import logging
+from typing import Any
+
+from better_notion._cli.docs.base import Schema
+
+logger = logging.getLogger(__name__)
+
+
+class SchemaRegistry:
+    """Registry for plugin documentation schemas.
+
+    This class maintains a collection of plugin schemas that
+    AI agents can query to understand the system.
+
+    Example:
+        >>> # Register a plugin schema
+        >>> SchemaRegistry.register("agents", AGENTS_SCHEMA)
+        >>>
+        >>> # Query for a plugin schema
+        >>> schema = SchemaRegistry.get("agents")
+        >>>
+        >>> # List all available schemas
+        >>> all_schemas = SchemaRegistry.list_all()
+    """
+
+    _schemas: dict[str, Schema] = {}
+
+    @classmethod
+    def register(cls, plugin_name: str, schema: Schema) -> None:
+        """Register a plugin schema.
+
+        Args:
+            plugin_name: Name of the plugin (e.g., "agents")
+            schema: Schema object containing plugin documentation
+        """
+        cls._schemas[plugin_name] = schema
+        logger.info(f"Registered schema for plugin: {plugin_name}")
+
+    @classmethod
+    def get(cls, plugin_name: str) -> Schema | None:
+        """Get a plugin schema by name.
+
+        Args:
+            plugin_name: Name of the plugin
+
+        Returns:
+            Schema object if found, None otherwise
+        """
+        return cls._schemas.get(plugin_name)
+
+    @classmethod
+    def list_all(cls) -> dict[str, Schema]:
+        """List all registered plugin schemas.
+
+        Returns:
+            Dict mapping plugin names to Schema objects
+        """
+        return cls._schemas.copy()
+
+    @classmethod
+    def get_all_names(cls) -> list[str]:
+        """Get list of all registered plugin names.
+
+        Returns:
+            List of plugin names
+        """
+        return list(cls._schemas.keys())
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered schemas.
+
+        This is primarily useful for testing.
+        """
+        cls._schemas.clear()
+        logger.debug("Cleared schema registry")