@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/examples/bridges/aiflow-bridge-example.yml

@@ -0,0 +1,310 @@
+# ============================================================================
+# OSSA Framework Bridge Example: AIFlow-Agent Integration
+# ============================================================================
+#
+# PURPOSE:
+#   Demonstrates OSSA's bridge pattern for integrating with AIFlow-Agent,
+#   a social agent framework for autonomous cryptocurrency market analysis
+#   and social media presence on Twitter, Telegram, and Discord.
+#
+# KEY FEATURES:
+#   - Character-based personality system (CryptoSage persona)
+#   - Multi-platform social media integration (Twitter/Telegram/Discord)
+#   - BNB Chain on-chain data analysis via web3
+#   - Autonomous posting with human approval workflow
+#   - Message style guides for consistent voice
+#
+# ARCHITECTURE:
+#   OSSA Agent (chat role)
+#     ↓ (bridge configuration)
+#   AIFlow-Agent Runtime
+#     ↓ (social platforms)
+#   Twitter API / Telegram Bot / Discord Bot
+#     ↓ (blockchain data)
+#   BNB Chain RPC (web3)
+#
+# USE CASE:
+#   Autonomous crypto analyst agent that:
+#   1. Monitors BNB Chain DeFi protocols and token metrics
+#   2. Analyzes market trends using AI
+#   3. Engages with community via social media
+#   4. Posts educational content and data-driven insights
+#
+# BRIDGE PATTERN:
+#   The `bridge.aiflow` extension translates OSSA agent capabilities
+#   into AIFlow's character-based configuration, enabling OSSA agents
+#   to leverage AIFlow's social agent infrastructure.
+#
+# RELATED DOCUMENTATION:
+#   - AIFlow-Agent: https://github.com/aiflowagent/aiflowagent
+#   - OSSA Bridge Spec: spec/OSSA_Bridge_Pattern.md
+#   - BNB Chain: https://www.bnbchain.org
+# ============================================================================
+
+# OSSA specification version
+ossaVersion: "1.0"
+
+agent:
+  # Unique agent identifier (DNS-compatible)
+  id: crypto-analyst-agent
+
+  # Human-readable name
+  name: Crypto Market Analyst
+
+  # Semantic version
+  version: 1.0.0
+
+  # Description of agent's purpose and capabilities
+  description: OSSA agent with AIFlow-Agent bridge for social crypto analysis
+
+  # Role: "chat" indicates interactive, conversational agent
+  # (as opposed to "worker" for task-based or "orchestrator" for coordination)
+  role: chat
+
+  # Tags for discovery and categorization
+  tags: ["crypto", "social", "bnb-chain", "twitter", "aiflow"]
+
+  # Runtime configuration
+  runtime:
+    # Serverless deployment (AWS Lambda, Cloudflare Workers, etc.)
+    type: serverless
+
+    # Python runtime requirements
+    requirements:
+      python: ">=3.11"        # Python 3.11+ for modern async features
+      packages:
+        - "aiflow-agent"      # AIFlow social agent framework
+        - "web3"              # Ethereum/BNB Chain interaction
+        - "tweepy"            # Twitter API v2 client
+
+  # Capabilities define what this agent can do (contract-first design)
+  capabilities:
+    # ========================================================================
+    # Capability 1: Analyze Market
+    # ========================================================================
+    # Analyzes cryptocurrency market trends for a specific token and timeframe.
+    # Uses on-chain data (BNB Chain) + LLM reasoning to generate sentiment.
+    # ========================================================================
+    - name: analyze_market
+
+      description: Analyze cryptocurrency market trends
+
+      # Input: token symbol and analysis timeframe
+      input_schema:
+        type: object
+        properties:
+          token:
+            type: string            # Token symbol (e.g., "BNB", "CAKE")
+          timeframe:
+            type: string
+            enum: ["1h", "24h", "7d", "30d"]  # Analysis window
+
+      # Output: sentiment analysis with confidence score
+      output_schema:
+        type: object
+        properties:
+          sentiment:
+            type: string
+            enum: ["bullish", "bearish", "neutral"]  # Market direction
+          confidence:
+            type: number            # 0.0-1.0 confidence in sentiment
+          summary:
+            type: string            # Human-readable analysis summary
+
+    # ========================================================================
+    # Capability 2: Post Analysis
+    # ========================================================================
+    # Posts market analysis to social media platforms.
+    # Requires manual approval (auto_post: false in bridge config).
+    # ========================================================================
+    - name: post_analysis
+
+      description: Post market analysis to social media
+
+      # Input: target platform and content to post
+      input_schema:
+        type: object
+        properties:
+          platform:
+            type: string
+            enum: ["twitter", "telegram", "discord"]  # Target social platform
+          content:
+            type: string            # Post content (character limits apply)
+
+      # Output: posting result with URL reference
+      output_schema:
+        type: object
+        properties:
+          posted:
+            type: boolean           # Success/failure indicator
+          post_url:
+            type: string            # URL to the posted content
+
+  # Observability configuration
+  monitoring:
+    traces: true      # Distributed tracing for multi-platform interactions
+    metrics: true     # Prometheus metrics for engagement analytics
+    logs: true        # Structured logging for audit trail
+
+  # ========================================================================
+  # AIFlow-Agent Bridge Configuration
+  # ========================================================================
+  # This section configures the AIFlow-Agent integration, defining the
+  # agent's personality, social platform connections, and behavior rules.
+  #
+  # AIFlow uses a "character" model where agents have:
+  # - Personality traits and bio
+  # - Lore and background story
+  # - Topic expertise areas
+  # - Communication style guides
+  # - Example messages for few-shot learning
+  # ========================================================================
+  bridge:
+    aiflow:
+      # Enable AIFlow bridge (false = use native OSSA runtime)
+      enabled: true
+
+      # Character definition (AIFlow personality system)
+      character:
+        # Character name (used in responses and attribution)
+        name: "CryptoSage"
+
+        # Social media handle/username
+        username: "@CryptoSageAI"
+
+        # Personality traits define the character's voice and behavior
+        # These guide LLM prompting for consistent persona
+        personality_traits:
+          - "analytical"              # Data-driven reasoning
+          - "data-driven"             # Evidence-based conclusions
+          - "cautiously optimistic"   # Balanced market perspective
+          - "educational"             # Teaching-oriented communication
+
+        # Bio appears on social profiles and in agent descriptions
+        bio: "AI-powered crypto analyst on BNB Chain. I analyze markets, share insights, and help you navigate the crypto space. Not financial advice!"
+
+        # Lore provides background story for character consistency
+        # Helps LLM understand the character's context and motivations
+        lore:
+          - "Created by the OSSA community to democratize crypto analysis"
+          - "Trained on millions of blockchain transactions and market data"
+          - "Believes in transparent, data-driven investment decisions"
+
+        # Topics the character is knowledgeable about
+        # Used for relevance filtering and topic modeling
+        topics:
+          - "BNB Chain ecosystem"
+          - "DeFi protocols"
+          - "Market analysis"
+          - "Blockchain technology"
+          - "Trading strategies"
+
+        # Style guides control communication patterns
+        # Different contexts (chat vs. posts) have different rules
+        style:
+          # Rules that apply to all interactions
+          all:
+            - "Use data and metrics to support claims"
+            - "Explain complex concepts simply"
+            - "Always include risk disclaimers"
+
+          # Chat-specific style (1-on-1 conversations)
+          chat:
+            - "Be helpful and educational"
+            - "Ask clarifying questions"
+            - "Provide actionable insights"
+
+          # Post-specific style (public social media)
+          post:
+            - "Lead with the key insight"
+            - "Use emojis sparingly (📊📈)"
+            - "Include relevant hashtags"
+
+        # Adjectives for character description (used in prompts)
+        adjectives:
+          - "analytical"
+          - "transparent"
+          - "educational"
+          - "data-focused"
+
+        # Few-shot learning examples for consistent response patterns
+        # AIFlow uses these to prime the LLM for character voice
+        # Conversation examples (few-shot learning for chat interactions)
+        # Format: user query → character response
+        message_examples:
+          - - user: "CryptoSage"
+              content:
+                text: "What's your take on BNB's price movement today?"
+            - character: "CryptoSage"
+              content:
+                # Example response demonstrating desired voice:
+                # - Starts with data
+                # - Uses specific metrics
+                # - Includes risk disclaimer (DYOR)
+                # - Sparing emoji use
+                text: "Looking at the 24h data: BNB is up 3.2% with volume increase of 15%. RSI at 62 suggests moderate bullish momentum. Key resistance at $610. Always DYOR! 📊"
+
+        # Post examples (few-shot learning for social media posts)
+        # These demonstrate the character's posting style and format
+        post_examples:
+          - "📊 BNB Chain TVL hit $5.2B today (+8% week over week). Pancakeswap leading with $2.1B. DeFi summer on BSC? Data suggests sustained growth. #BNB #DeFi #CryptoAnalysis"
+          - "🔍 Analyzing top 100 BNB Chain tokens: 67% showing positive 7d trends, avg volume up 12%. Market sentiment: Cautiously optimistic. Full breakdown 👇"
+
+      # ======================================================================
+      # Blockchain Integration (BNB Chain)
+      # ======================================================================
+      # Enables on-chain data analysis via web3.py
+      # ======================================================================
+      blockchain:
+        enabled: true
+        network: mainnet                # mainnet or testnet
+        wallet_address: "0x..."         # BNB Chain wallet for on-chain analysis
+                                        # (read-only, no private key in manifest)
+
+      # ======================================================================
+      # Social Platform Connections
+      # ======================================================================
+      # Configures social media integrations for multi-platform presence.
+      # Credentials are injected via environment variables (not in manifest).
+      # ======================================================================
+      social_platforms:
+        # Twitter integration (via tweepy)
+        twitter:
+          enabled: true
+          username: "@CryptoSageAI"
+          auto_post: false              # Requires manual approval for safety
+
+        # Telegram bot integration
+        telegram:
+          enabled: true
+          bot_token: "${TELEGRAM_BOT_TOKEN}"  # Env var substitution
+
+        # Discord bot integration
+        discord:
+          enabled: true
+          bot_token: "${DISCORD_BOT_TOKEN}"   # Env var substitution
+
+# ============================================================================
+# End of AIFlow Bridge Example
+# ============================================================================
+#
+# VALIDATION:
+#   ossa validate examples/bridges/aiflow-bridge-example.yml
+#
+# DEPLOYMENT:
+#   1. Install AIFlow-Agent: pip install aiflow-agent
+#   2. Set environment variables: TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN
+#   3. Configure social platform API keys in .env file
+#   4. Deploy to serverless: ossa deploy crypto-analyst-agent --platform aws-lambda
+#
+# BRIDGE PATTERN NOTES:
+#   - The `bridge.aiflow` section is translated into AIFlow character.json
+#   - OSSA capabilities map to AIFlow action handlers
+#   - Social platform configs generate AIFlow client configurations
+#   - Character personality informs LLM system prompts
+#
+# RELATED EXAMPLES:
+#   - examples/drupal/gitlab-ml-recommender.ossa.yaml (Drupal bridge)
+#   - examples/openapi-extensions/minimal-agent-api.openapi.yml (OpenAPI)
+#   - spec/OSSA_Bridge_Pattern.md (bridge specification)
+# ============================================================================

package/examples/bridges/aiflow-phoenix-tracing.py

@@ -0,0 +1,310 @@
+"""
+Phoenix Tracing Integration for AIFlow FastAPI Bridge
+
+This module adds OpenTelemetry/Phoenix tracing to the AIFlow FastAPI bridge.
+Traces all API calls, LLM interactions, and agent tasks.
+
+Usage:
+    from aiflow_phoenix_tracing import init_phoenix_tracing, trace_agent_task
+
+    # Initialize at startup
+    init_phoenix_tracing(
+        service_name="social-agent-aiflow",
+        phoenix_endpoint="http://otel.agent-buildkit.orb.local:4318",
+        phoenix_project="aiflow-social-agents"
+    )
+
+    # Trace agent tasks
+    @trace_agent_task("generate_post")
+    async def generate_post(request):
+        # Your code here
+        pass
+"""
+
+import os
+import time
+from typing import Optional, Dict, Any, Callable
+from functools import wraps
+
+# OpenTelemetry imports
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.semconv.resource import ResourceAttributes
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentation
+from opentelemetry.instrumentation.requests import RequestsInstrumentation
+from opentelemetry.trace import Status, StatusCode, SpanKind
+
+
+# Global tracer
+_tracer: Optional[trace.Tracer] = None
+_phoenix_config: Dict[str, Any] = {}
+
+
+def init_phoenix_tracing(
+    service_name: str,
+    phoenix_endpoint: Optional[str] = None,
+    phoenix_project: Optional[str] = None,
+    enable_console_export: bool = False,
+):
+    """
+    Initialize Phoenix tracing for the AIFlow agent.
+    
+    Args:
+        service_name: Name of the service (e.g., 'social-agent-aiflow')
+        phoenix_endpoint: Phoenix OTLP endpoint (default: env PHOENIX_ENDPOINT)
+        phoenix_project: Phoenix project name (default: env PHOENIX_PROJECT)
+        enable_console_export: Export traces to console for debugging
+    """
+    global _tracer, _phoenix_config
+    
+    # Get config from environment if not provided
+    phoenix_endpoint = phoenix_endpoint or os.getenv(
+        'PHOENIX_ENDPOINT',
+        'http://otel.agent-buildkit.orb.local:4318'
+    )
+    phoenix_project = phoenix_project or os.getenv(
+        'PHOENIX_PROJECT',
+        'aiflow-social-agents'
+    )
+    
+    # Store config
+    _phoenix_config = {
+        'service_name': service_name,
+        'phoenix_endpoint': phoenix_endpoint,
+        'phoenix_project': phoenix_project,
+    }
+    
+    # Create resource
+    resource = Resource.create({
+        ResourceAttributes.SERVICE_NAME: service_name,
+        ResourceAttributes.SERVICE_VERSION: os.getenv('SERVICE_VERSION', '1.0.0'),
+        ResourceAttributes.DEPLOYMENT_ENVIRONMENT: os.getenv('NODE_ENV', 'development'),
+        'phoenix.project': phoenix_project,
+        'agent.type': 'aiflow',
+        'agent.framework': 'fastapi',
+    })
+    
+    # Create tracer provider
+    provider = TracerProvider(resource=resource)
+    
+    # Add OTLP exporter
+    otlp_exporter = OTLPSpanExporter(
+        endpoint=f"{phoenix_endpoint}/v1/traces",
+        headers={
+            'x-phoenix-project': phoenix_project,
+        },
+    )
+    
+    provider.add_span_processor(
+        BatchSpanProcessor(
+            otlp_exporter,
+            max_queue_size=1000,
+            max_export_batch_size=100,
+            schedule_delay_millis=1000,
+        )
+    )
+    
+    # Set as global tracer provider
+    trace.set_tracer_provider(provider)
+    
+    # Get tracer
+    _tracer = trace.get_tracer(service_name)
+    
+    # Auto-instrument FastAPI and Requests
+    FastAPIInstrumentation().instrument()
+    RequestsInstrumentation().instrument()
+    
+    print(f"✅ Phoenix tracing initialized")
+    print(f"   Service: {service_name}")
+    print(f"   Project: {phoenix_project}")
+    print(f"   Endpoint: {phoenix_endpoint}")
+    print(f"   View traces: http://phoenix.agent-buildkit.orb.local:6006/projects/{phoenix_project}")
+
+
+def get_tracer() -> trace.Tracer:
+    """Get the global tracer instance."""
+    if _tracer is None:
+        raise RuntimeError("Phoenix tracing not initialized. Call init_phoenix_tracing() first.")
+    return _tracer
+
+
+def trace_agent_task(task_name: str):
+    """
+    Decorator to trace agent tasks.
+    
+    Usage:
+        @trace_agent_task("generate_post")
+        async def generate_post(request):
+            # Your code here
+            pass
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            tracer = get_tracer()
+            
+            with tracer.start_as_current_span(
+                f"agent.task.{task_name}",
+                kind=SpanKind.INTERNAL,
+                attributes={
+                    'agent.task': task_name,
+                    'agent.type': 'aiflow',
+                    'agent.service': _phoenix_config.get('service_name', 'unknown'),
+                }
+            ) as span:
+                try:
+                    start_time = time.time()
+                    result = await func(*args, **kwargs)
+                    duration_ms = (time.time() - start_time) * 1000
+                    
+                    # Add success attributes
+                    span.set_attribute('agent.task.duration_ms', duration_ms)
+                    span.set_attribute('agent.task.status', 'success')
+                    span.set_status(Status(StatusCode.OK))
+                    
+                    return result
+                    
+                except Exception as e:
+                    # Add error attributes
+                    span.set_attribute('agent.task.status', 'error')
+                    span.set_attribute('agent.task.error', str(e))
+                    span.set_status(Status(StatusCode.ERROR, str(e)))
+                    span.record_exception(e)
+                    raise
+        
+        return wrapper
+    return decorator
+
+
+def trace_llm_call(
+    provider: str,
+    model: str,
+    prompt: str,
+    response: Optional[str] = None,
+    input_tokens: Optional[int] = None,
+    output_tokens: Optional[int] = None,
+    cost: Optional[float] = None,
+):
+    """
+    Add LLM-specific attributes to current span.
+    
+    Args:
+        provider: LLM provider (e.g., 'anthropic', 'openai')
+        model: Model name (e.g., 'claude-3-sonnet')
+        prompt: Input prompt
+        response: Generated response
+        input_tokens: Number of input tokens
+        output_tokens: Number of output tokens
+        cost: Estimated cost in USD
+    """
+    span = trace.get_current_span()
+    if span.is_recording():
+        span.set_attribute('llm.provider', provider)
+        span.set_attribute('llm.model', model)
+        span.set_attribute('llm.prompt', prompt[:500])  # Truncate long prompts
+        
+        if response:
+            span.set_attribute('llm.response', response[:500])
+        
+        if input_tokens is not None:
+            span.set_attribute('llm.tokens.input', input_tokens)
+        
+        if output_tokens is not None:
+            span.set_attribute('llm.tokens.output', output_tokens)
+        
+        if input_tokens and output_tokens:
+            span.set_attribute('llm.tokens.total', input_tokens + output_tokens)
+        
+        if cost is not None:
+            span.set_attribute('llm.cost', cost)
+
+
+def trace_character_interaction(
+    character_name: str,
+    interaction_type: str,
+    platform: Optional[str] = None,
+    mood: Optional[str] = None,
+):
+    """
+    Add AIFlow character-specific attributes to current span.
+    
+    Args:
+        character_name: Name of the AIFlow character
+        interaction_type: Type of interaction ('post', 'response', 'conversation')
+        platform: Social platform ('twitter', 'telegram', etc.)
+        mood: Character's current mood
+    """
+    span = trace.get_current_span()
+    if span.is_recording():
+        span.set_attribute('aiflow.character', character_name)
+        span.set_attribute('aiflow.interaction_type', interaction_type)
+        
+        if platform:
+            span.set_attribute('aiflow.platform', platform)
+        
+        if mood:
+            span.set_attribute('aiflow.mood', mood)
+
+
+def create_span(span_name: str, attributes: Optional[Dict[str, Any]] = None) -> trace.Span:
+    """
+    Create a new span for manual instrumentation.
+    
+    Args:
+        span_name: Name of the span
+        attributes: Optional attributes to add to the span
+    
+    Returns:
+        Span context manager
+    
+    Usage:
+        with create_span('my_operation', {'key': 'value'}) as span:
+            # Your code here
+            pass
+    """
+    tracer = get_tracer()
+    span = tracer.start_span(span_name)
+    
+    if attributes:
+        for key, value in attributes.items():
+            span.set_attribute(key, value)
+    
+    return span
+
+
+# Example usage in FastAPI app
+if __name__ == '__main__':
+    # This would be called in your FastAPI startup
+    init_phoenix_tracing(
+        service_name='social-agent-aiflow',
+        phoenix_endpoint='http://otel.agent-buildkit.orb.local:4318',
+        phoenix_project='aiflow-social-agents'
+    )
+    
+    # Example traced function
+    @trace_agent_task('generate_social_post')
+    async def generate_social_post(platform: str, mood: str):
+        # Add character interaction metadata
+        trace_character_interaction(
+            character_name='AIFlow',
+            interaction_type='post',
+            platform=platform,
+            mood=mood
+        )
+        
+        # Simulate LLM call
+        trace_llm_call(
+            provider='anthropic',
+            model='claude-3-sonnet',
+            prompt='Generate a social media post',
+            response='Hello world!',
+            input_tokens=150,
+            output_tokens=50,
+            cost=0.001
+        )
+        
+        return {'content': 'Hello world!', 'platform': platform}
+