claritty-sdk 1.0.0__py3-none-any.whl

claritty_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: claritty-sdk
+Version: 1.0.0
+Summary: Professional SDK for building AI-powered agentic applications on Clarity Platform
+Home-page: https://github.com/Clarittyai/claritty-sdk
+Author: Clarity Platform
+Author-email: Clarity Platform <developers@clarity.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/Clarittyai/claritty-sdk
+Project-URL: Documentation, https://github.com/Clarittyai/claritty-sdk#readme
+Project-URL: Repository, https://github.com/Clarittyai/claritty-sdk
+Project-URL: Issues, https://github.com/Clarittyai/claritty-sdk/issues
+Keywords: ai,agents,workflows,automation,clarity,agentic,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: croniter>=2.0.1
+Requires-Dist: pytz>=2024.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=24.1.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Clarity SDK
+
+Professional Python SDK for building AI-powered agentic applications on the Clarity platform.
+
+## Features
+
+- **🤖 Agent Decorator** - Define AI agents with clean, declarative syntax
+- **🔄 Workflow Orchestration** - Chain agents into multi-step workflows
+- **⏰ User-Configurable Triggers** - Let users control when workflows run
+- **🔌 Integration Management** - OAuth/API key handling built-in
+- **📊 Type Safety** - Full Pydantic validation
+- **🧪 Production Ready** - Error handling, retries, timeouts included
+
+## Installation
+
+```bash
+pip install clarity-sdk
+```
+
+## Quick Start
+
+### 1. Define an Agent
+
+```python
+from clarity_sdk import agent, BaseAgent, AgentContext, AgentResult
+
+@agent(
+    id="task-prioritizer",
+    name="Task Prioritizer",
+    description="Analyzes tasks and suggests priorities",
+    inputs={"tasks": list},
+    outputs={"priorities": dict},
+    category="productivity"
+)
+class TaskPrioritizerAgent(BaseAgent):
+    async def execute(self, context: AgentContext) -> AgentResult:
+        tasks = context.get_input("tasks", [])
+
+        # Your AI logic here
+        priorities = self._analyze_tasks(tasks)
+
+        return AgentResult(
+            success=True,
+            data={"priorities": priorities}
+        )
+
+    def _analyze_tasks(self, tasks):
+        # Use LangChain, Claude SDK, or your own logic
+        return {"high": [], "medium": [], "low": []}
+```
+
+### 2. Create a Workflow
+
+```python
+from clarity_sdk import workflow, uses_agent, ExecutionMode
+
+@workflow(
+    id="daily-task-summary",
+    name="Daily Task Summary",
+    description="Analyzes tasks and sends Slack summary",
+    execution_mode=ExecutionMode.SEQUENTIAL
+)
+@uses_agent("task-prioritizer", output_key="priorities")
+@uses_agent("slack-notifier", input_from="priorities")
+async def daily_task_summary(context):
+    # Workflow executes automatically based on @uses_agent chain
+    pass
+```
+
+### 3. Define a Trigger Template
+
+```python
+from clarity_sdk import trigger_template, TriggerTemplateType
+
+@trigger_template(
+    id="daily-review",
+    name="Daily Task Review",
+    description="Review your tasks at a specific time each day",
+    template_type=TriggerTemplateType.SCHEDULE_DAILY,
+    workflow_id="daily-task-summary",
+    config_fields=[
+        {
+            "key": "time",
+            "label": "What time?",
+            "type": "time",
+            "required": True,
+            "default": "09:00"
+        },
+        {
+            "key": "timezone",
+            "label": "Your Timezone",
+            "type": "timezone",
+            "required": True
+        }
+    ]
+)
+class DailyReviewTrigger:
+    pass
+```
+
+**User Experience:**
+- User sees "Daily Task Review" in platform UI
+- User clicks "Create Trigger"
+- User configures: 9:00 AM, America/New_York
+- Workflow runs every day at 9 AM EST for that user!
+
+## Core Concepts
+
+### Agents
+
+Agents are individual AI-powered units that perform specific tasks.
+
+```python
+@agent(
+    id="unique-id",
+    name="User-Facing Name",
+    description="What this agent does",
+    inputs={"key": type},      # Expected inputs
+    outputs={"key": type},     # Expected outputs
+    category="productivity",   # Category
+    timeout=300               # Timeout in seconds
+)
+class MyAgent(BaseAgent):
+    async def execute(self, context):
+        # Your logic
+        return AgentResult(success=True, data={...})
+```
+
+### Workflows
+
+Workflows orchestrate multiple agents.
+
+```python
+@workflow(id="my-workflow", name="My Workflow")
+@uses_agent("agent-1", output_key="step1")
+@uses_agent("agent-2", input_from="step1", output_key="step2")
+async def my_workflow(context):
+    # Optional custom logic
+    pass
+```
+
+### Triggers
+
+Triggers define when workflows run - **configured by end users**.
+
+```python
+@trigger_template(
+    id="my-trigger",
+    template_type=TriggerTemplateType.SCHEDULE_DAILY,
+    workflow_id="my-workflow",
+    config_fields=[...]  # User-configurable fields
+)
+class MyTrigger:
+    pass
+```
+
+## Integration Requirements
+
+Agents can declare integration requirements (OAuth, API keys):
+
+```python
+@agent(
+    id="slack-notifier",
+    integrations=[{
+        "service": "slack",
+        "auth_type": "oauth",
+        "description": "Connect your Slack workspace",
+        "scopes": ["chat:write"],
+        "config_fields": [{
+            "key": "bot_token",
+            "label": "Bot Token",
+            "type": "password",
+            "required": True
+        }]
+    }]
+)
+class SlackNotifierAgent(BaseAgent):
+    async def execute(self, context):
+        # Get user's connected Slack credentials
+        slack = context.get_integration("slack")
+
+        if not slack:
+            return AgentResult(
+                success=False,
+                error="Slack not connected"
+            )
+
+        # Use credentials
+        # ...
+```
+
+## Context Objects
+
+### AgentContext
+
+Provided to agents during execution:
+
+```python
+# Get input data
+tasks = context.get_input("tasks", [])
+
+# Get integration credentials
+slack = context.get_integration("slack")
+
+# Get workflow data
+previous_result = context.get_workflow_data("previous_step")
+
+# Get app config
+api_key = context.get_config("api_key")
+
+# Log
+context.log("info", "Processing tasks", count=len(tasks))
+```
+
+### WorkflowContext
+
+Provided to workflows:
+
+```python
+# Get trigger data
+trigger_data = context.get_trigger_data()
+
+# Get step outputs
+analysis = context.get_step_output("analysis")
+
+# Log
+context.log("info", "Workflow started")
+```
+
+## Trigger Template Types
+
+| Type | Description | User Configures |
+|------|-------------|-----------------|
+| `SCHEDULE_DAILY` | Daily at specific time | Time, timezone, days |
+| `SCHEDULE_CRON` | Custom cron expression | Cron expression, timezone |
+| `SCHEDULE_INTERVAL` | Every X seconds | Interval duration |
+| `DATA_THRESHOLD` | When value crosses threshold | Metric, threshold, operator |
+| `DATA_CHANGE` | When database record changes | Table, operation, filter |
+| `WEBHOOK` | External webhook | Endpoint, auth |
+| `MANUAL` | User clicks button | Nothing (just execute) |
+
+## Config Field Types
+
+For `config_fields` in trigger templates:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `time` | Time picker (HH:MM) | "09:00" |
+| `timezone` | Timezone selector | "America/New_York" |
+| `number` | Numeric input | 42 |
+| `text` | Text input | "My trigger" |
+| `select` | Dropdown | "option1" |
+| `multiselect` | Multiple choice | ["opt1", "opt2"] |
+| `boolean` | Toggle | true |
+| `cron` | Cron expression | "0 9 * * 1-5" |
+| `secret` | Auto-generated secret | (hidden) |
+| `date` | Date picker | "2026-02-18" |
+| `datetime` | DateTime picker | "2026-02-18T09:00:00Z" |
+
+## Development
+
+### Install for Development
+
+```bash
+git clone https://github.com/clarity-platform/clarity-sdk
+cd clarity-sdk
+pip install -e ".[dev]"
+```
+
+### Run Tests
+
+```bash
+pytest
+pytest --cov=clarity_sdk  # With coverage
+```
+
+### Type Checking
+
+```bash
+mypy clarity_sdk
+```
+
+### Formatting
+
+```bash
+black clarity_sdk
+```
+
+## Examples
+
+See the `/examples` directory for complete examples:
+
+- `examples/task_manager/` - Task management app with Slack integration
+- `examples/data_pipeline/` - Data processing pipeline with parallel execution
+- `examples/chatbot/` - Conversational agent with memory
+
+## Documentation
+
+- [Complete Design Document](../AGENTIC_APP_SEED_COMPLETE_DESIGN.md)
+- [Trigger System Design](../TRIGGER_SYSTEM_DESIGN.md)
+- [API Reference](https://docs.clarity.com/sdk)
+
+## Support
+
+- **Discord**: https://discord.gg/clarity
+- **Documentation**: https://docs.clarity.com
+- **Issues**: https://github.com/clarity-platform/clarity-sdk/issues
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+---
+
+**Built with ❤️ by the Clarity Platform team**

claritty_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+claritty_sdk-1.0.0.dist-info/licenses/LICENSE,sha256=e17pOMoFOeijUVj1fQs277Txrf1WM515hJeK7Say9Ik,1073
+clarity_sdk/__init__.py,sha256=Vw2dPqUe03lVJPRyWlN3lXjUs573L43mslc6_jQHBfI,2231
+clarity_sdk/agent.py,sha256=y4h-fgYIGMXDBSc26xHYUOcB5mSipDRMZBDikkkR97U,5637
+clarity_sdk/base.py,sha256=MOvzZoUyVoh4jDZFTwSOMSTJda9D54i1RUKcdI9dN2Y,2450
+clarity_sdk/context.py,sha256=TySicF8TXPV13OpBoMyBUhbKHNWuVtFvShjvnSYRVCs,8311
+clarity_sdk/exceptions.py,sha256=PoChg9mbzR0m9q7hgVIenNXFkcOyraYmXM79h61tucc,800
+clarity_sdk/executor.py,sha256=wgTu1ph7bfM47UHVDYvPfHoOvf65yvZsi5dOaHbFBTs,18919
+clarity_sdk/models.py,sha256=Ecc34TAu0Oqx4E8i_8q1hZLY7cpSdcd2QmaZ4s_dr0c,7633
+clarity_sdk/registry.py,sha256=2IfyExipnBPr73mB7UmGg-cth_GprC7qfuBmS8i9D24,5179
+clarity_sdk/setup.py,sha256=7D29XJyKAiZ2pbNEITkTkz6cwPlI3A0tBNY7YPR7ZxY,1294
+clarity_sdk/trigger.py,sha256=yCga59mBlkNHKGL5wqr6TR47Yaw3kKcmKmDNEz2cOhs,8882
+clarity_sdk/trigger_manager.py,sha256=voGmjBGSX-MtkfjvscLpqF_3zIs3wtydmCjklFIVlnA,18743
+clarity_sdk/workflow.py,sha256=WFKYSKhwA2Lv55XWeVlSUWshRcYIEJQnZOOVy1J9F7k,6998
+claritty_sdk-1.0.0.dist-info/METADATA,sha256=u4VHY2JdUV3hfwJYPTQZAxRU0YSDV2lwaRm-LI0jx80,9380
+claritty_sdk-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+claritty_sdk-1.0.0.dist-info/top_level.txt,sha256=mBhpBOZR9rCUlD2pYA243Avvlv49bCR498LhfbQ2dis,12
+claritty_sdk-1.0.0.dist-info/RECORD,,

claritty_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

claritty_sdk-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Clarity Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claritty_sdk-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clarity_sdk

clarity_sdk/__init__.py

@@ -0,0 +1,98 @@
+"""
+Clarity SDK - Professional SDK for building AI-powered agentic applications
+
+Provides decorators and utilities for defining:
+- AI Agents (@agent)
+- Workflows (@workflow, @uses_agent)
+- Trigger Templates (@trigger_template)
+- Integrations and context management
+
+Example:
+    from clarity_sdk import agent, workflow, uses_agent, BaseAgent, AgentResult
+
+    @agent(
+        id="my-agent",
+        name="My Agent",
+        inputs={"text": str},
+        outputs={"result": str}
+    )
+    class MyAgent(BaseAgent):
+        async def execute(self, context):
+            return AgentResult(success=True, data={"result": "processed"})
+
+    @workflow(id="my-workflow")
+    @uses_agent("my-agent")
+    async def my_workflow(context):
+        pass
+"""
+
+__version__ = "1.0.0"
+__author__ = "Clarity Platform"
+
+# Core decorators
+from clarity_sdk.agent import agent
+from clarity_sdk.workflow import workflow, uses_agent
+from clarity_sdk.trigger import trigger_template, TriggerTemplateType
+
+# Base classes
+from clarity_sdk.base import BaseAgent, AgentResult
+
+# Context objects
+from clarity_sdk.context import AgentContext, WorkflowContext
+
+# Registries (for advanced usage)
+from clarity_sdk.registry import AgentRegistry, WorkflowRegistry, TriggerTemplateRegistry
+
+# Exceptions
+from clarity_sdk.exceptions import (
+    ClaritySDKError,
+    AgentError,
+    WorkflowError,
+    TriggerError,
+    ValidationError,
+    ExecutionError
+)
+
+# Enums
+from clarity_sdk.workflow import ExecutionMode
+
+# Executors (optional - for advanced usage)
+from clarity_sdk.executor import WorkflowExecutor
+from clarity_sdk.trigger_manager import DynamicTriggerManager
+
+__all__ = [
+    # Decorators
+    "agent",
+    "workflow",
+    "uses_agent",
+    "trigger_template",
+
+    # Base classes
+    "BaseAgent",
+    "AgentResult",
+
+    # Context
+    "AgentContext",
+    "WorkflowContext",
+
+    # Registries
+    "AgentRegistry",
+    "WorkflowRegistry",
+    "TriggerTemplateRegistry",
+
+    # Enums
+    "ExecutionMode",
+    "TriggerTemplateType",
+
+    # Exceptions
+    "ClaritySDKError",
+    "AgentError",
+    "WorkflowError",
+    "TriggerError",
+    "ValidationError",
+    "ExecutionError",
+
+    # Executors (advanced)
+    "WorkflowExecutor",
+    "DynamicTriggerManager",
+]

clarity_sdk/agent.py

@@ -0,0 +1,163 @@
+"""
+Agent decorator for defining AI agents
+
+The @agent decorator registers agents with metadata and makes them
+discoverable by the platform.
+
+Example:
+    from clarity_sdk import agent, BaseAgent, AgentResult, AgentContext
+
+    @agent(
+        id="task-prioritizer",
+        name="Task Prioritizer",
+        description="Analyzes tasks and suggests priorities",
+        inputs={"tasks": list},
+        outputs={"priorities": dict},
+        category="productivity"
+    )
+    class TaskPrioritizerAgent(BaseAgent):
+        async def execute(self, context: AgentContext) -> AgentResult:
+            tasks = context.get_input("tasks", [])
+            # Your AI logic here
+            return AgentResult(success=True, data={"priorities": {}})
+"""
+
+from typing import Dict, Any, List, Optional, Callable
+from functools import wraps
+from clarity_sdk.models import AgentMetadata, IntegrationRequirement
+from clarity_sdk.registry import AgentRegistry
+from clarity_sdk.exceptions import ValidationError, AgentError
+import inspect
+
+
+def agent(
+    id: str,
+    name: str,
+    description: str,
+    inputs: Dict[str, Any],
+    outputs: Dict[str, Any],
+    category: str = "general",
+    integrations: Optional[List[Dict[str, Any]]] = None,
+    capabilities: Optional[List[str]] = None,
+    version: str = "1.0.0",
+    rate_limit: Optional[Dict[str, int]] = None,
+    timeout: int = 300,
+    retry_policy: Optional[Dict[str, Any]] = None
+):
+    """
+    Decorator to define an AI agent with metadata.
+
+    The decorated class must inherit from BaseAgent and implement execute().
+
+    Args:
+        id: Unique agent identifier (lowercase, hyphens only)
+        name: User-facing name
+        description: What this agent does
+        inputs: Expected input schema (dict of key: type)
+        outputs: Expected output schema (dict of key: type)
+        category: Category for organization (default: "general")
+        integrations: List of integration requirements (optional)
+        capabilities: List of capability tags (optional)
+        version: Agent version (default: "1.0.0")
+        rate_limit: Rate limiting config {"calls": 100, "period": 3600}
+        timeout: Execution timeout in seconds (default: 300)
+        retry_policy: Retry configuration (optional)
+
+    Returns:
+        Decorated class with agent metadata
+
+    Raises:
+        ValidationError: If agent definition is invalid
+        TypeError: If class doesn't implement execute()
+
+    Example:
+        @agent(
+            id="slack-notifier",
+            name="Slack Notifier",
+            description="Send notifications to Slack",
+            inputs={"channel": str, "message": str},
+            outputs={"message_id": str, "success": bool},
+            category="integration",
+            integrations=[{
+                "service": "slack",
+                "auth_type": "oauth",
+                "description": "Connect your Slack workspace",
+                "scopes": ["chat:write"],
+                "config_fields": [{
+                    "key": "bot_token",
+                    "label": "Bot Token",
+                    "type": "password",
+                    "required": True
+                }]
+            }],
+            timeout=60
+        )
+        class SlackNotifierAgent(BaseAgent):
+            async def execute(self, context: AgentContext) -> AgentResult:
+                slack = context.get_integration("slack")
+                if not slack:
+                    return AgentResult(
+                        success=False,
+                        error="Slack not connected"
+                    )
+                # Send to Slack...
+                return AgentResult(success=True, data={...})
+    """
+
+    def decorator(cls):
+        # Validate class has execute method
+        if not hasattr(cls, 'execute'):
+            raise TypeError(
+                f"Agent class {cls.__name__} must implement execute() method. "
+                f"Make sure your class inherits from BaseAgent."
+            )
+
+        # Validate execute is async
+        execute_method = getattr(cls, 'execute')
+        if not inspect.iscoroutinefunction(execute_method):
+            raise TypeError(
+                f"Agent {cls.__name__}.execute() must be an async method. "
+                f"Use: async def execute(self, context)"
+            )
+
+        # Parse integrations
+        integration_objs = []
+        if integrations:
+            try:
+                for integ in integrations:
+                    integration_objs.append(IntegrationRequirement(**integ))
+            except Exception as e:
+                raise ValidationError(f"Invalid integration requirement: {e}")
+
+        # Create metadata
+        try:
+            metadata = AgentMetadata(
+                id=id,
+                name=name,
+                description=description,
+                version=version,
+                category=category,
+                inputs=inputs,
+                outputs=outputs,
+                integrations=integration_objs,
+                capabilities=capabilities or [],
+                rate_limit=rate_limit,
+                timeout=timeout,
+                retry_policy=retry_policy or {"max_retries": 3, "backoff": "exponential"}
+            )
+        except Exception as e:
+            raise ValidationError(f"Invalid agent metadata for {id}: {e}")
+
+        # Store metadata on class
+        cls._clarity_metadata = metadata
+        cls._clarity_type = "agent"
+
+        # Register agent globally
+        AgentRegistry.register(metadata, cls)
+
+        # Add helper methods to class
+        cls.get_metadata = classmethod(lambda c: metadata)
+
+        return cls
+
+    return decorator