@bluefly/openstandardagents 0.2.5-RC → 0.2.8

package/docs/brand-guide/07-application-examples.md

@@ -0,0 +1,153 @@
+# OSSA Brand Application Examples
+
+> Version 1.0.0 | Last Updated: November 2025
+
+## Website Hero
+
+```html
+<section class="hero bg-gradient-hero py-24 text-center">
+  <img src="/brand/ossa-logo.svg" alt="OSSA Logo" class="h-32 mx-auto mb-8">
+  <h1 class="text-display font-extrabold text-gray-900 mb-6">
+    The <span class="gradient-text">OpenAPI</span> for AI Agents
+  </h1>
+  <p class="text-body-large text-gray-700 max-w-3xl mx-auto mb-12">
+    Universal specification standard for interoperable AI agents
+  </p>
+  <div class="flex gap-4 justify-center">
+    <a href="#start" class="btn-primary">Get Started</a>
+    <a href="/docs" class="btn-outline">Documentation</a>
+  </div>
+</section>
+```
+
+## Feature Cards
+
+```html
+<div class="card card-interactive">
+  <div class="icon-container bg-primary-100 rounded-lg p-3 mb-4">
+    <svg class="icon-24 text-primary-600"><!-- Icon --></svg>
+  </div>
+  <h3 class="text-h4 font-semibold mb-3">Vendor-Neutral</h3>
+  <p class="text-body text-gray-700">
+    No vendor lock-in. Deploy anywhere, switch frameworks anytime.
+  </p>
+</div>
+```
+
+## Navigation Header
+
+```html
+<header class="sticky top-0 bg-white/95 backdrop-blur border-b border-gray-200">
+  <div class="container flex items-center justify-between h-16">
+    <a href="/" class="flex items-center gap-3">
+      <img src="/brand/ossa-logo.svg" alt="OSSA" class="h-8">
+      <div>
+        <div class="font-bold text-lg text-primary-600">OSSA</div>
+        <div class="text-xs text-gray-500">AI Agent Standard</div>
+      </div>
+    </a>
+    <nav class="flex gap-8">
+      <a href="/docs" class="nav-link active">Docs</a>
+      <a href="/examples" class="nav-link">Examples</a>
+    </nav>
+    <a href="#start" class="btn-primary">Get Started</a>
+  </div>
+</header>
+```
+
+## Documentation Page
+
+```html
+<div class="docs-layout flex">
+  <aside class="sidebar w-64 border-r p-6">
+    <a href="#" class="sidebar-link active">Installation</a>
+    <a href="#" class="sidebar-link">Quick Start</a>
+  </aside>
+  <main class="flex-1 max-w-4xl p-12">
+    <h1 class="text-h1 mb-6">Installation</h1>
+    <p class="text-body mb-4">Install OSSA using npm:</p>
+    <pre class="code-block"><code>npm install -g @bluefly/openstandardagents</code></pre>
+  </main>
+</div>
+```
+
+## Social Media
+
+**Twitter Card (1200×675px):**
+- Background: Gradient or white
+- Logo: 200px centered
+- Title: H2, bold
+- Description: Body text
+- CTA button
+- URL at bottom
+
+**GitHub Preview (1280×640px):**
+- Logo + "OSSA" + tagline
+- Large headline
+- Key features (checkmarks)
+- Repository URL
+
+## Email Template
+
+```html
+<table width="600" cellpadding="0" cellspacing="0">
+  <!-- Header with gradient background -->
+  <tr><td style="padding: 32px; background: linear-gradient(135deg, #1CB9ED, #4A3ECD, #9060EA);">
+    <img src="logo-white.svg" alt="OSSA" width="120">
+  </td></tr>
+  
+  <!-- Content -->
+  <tr><td style="padding: 32px; background: white;">
+    <h2 style="color: #4A3ECD;">What's New</h2>
+    <p style="color: #374151;">OSSA v0.2.5 released...</p>
+    <a href="..." style="display: inline-block; padding: 12px 32px; 
+       background: #4A3ECD; color: white; border-radius: 8px;">
+      Get Started
+    </a>
+  </td></tr>
+  
+  <!-- Footer -->
+  <tr><td style="padding: 24px; background: #F3F4F6; text-align: center;">
+    <p style="color: #6B7280;">openstandardagents.org</p>
+  </td></tr>
+</table>
+```
+
+## Presentation Slides
+
+**Title Slide:**
+- Centered logo (180px)
+- Title: Display size, gradient text option
+- Subtitle: H3 size, gray
+- Metadata: Small text at bottom
+
+**Content Slide:**
+- Small logo + title in header
+- Bulleted list with icons
+- Code/diagram boxes
+- Footer: URL + social
+
+## README Badges
+
+```markdown
+![OSSA Compliant](https://img.shields.io/badge/OSSA-Compliant-4A3ECD)
+![Version](https://img.shields.io/badge/OSSA-v0.2.5--RC-1CB9ED)
+![Vendor Neutral](https://img.shields.io/badge/Vendor-Neutral-10B981)
+```
+
+## Brand Assets
+
+**Request full package:**
+- Email: design@openstandardagents.org
+- Includes: Logos (all variants), color swatches, templates
+- Formats: SVG, PNG, AI, Figma
+
+## Checklist
+
+✅ Logo: Correct variant, minimum size
+✅ Colors: Approved palette, contrast requirements
+✅ Typography: Inter/JetBrains Mono, correct weights
+✅ Spacing: 4px grid system
+✅ Accessibility: WCAG AA minimum (AAA preferred)
+✅ Responsive: Mobile, tablet, desktop
+✅ Tone: Professional, clear, confident

package/docs/brand-guide/OssaLogo/OssA_Logo.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 284 180" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g id="Layer3">
+    </g>
+    <g id="Artboard1" transform="matrix(0.959459,0,0,0.967742,-85.391892,-77.419355)">
+        <rect x="89" y="80" width="296" height="186" style="fill:none;"/>
+        <g id="Layer2" transform="matrix(1.042254,0,0,1.033333,-98.605634,44.866667)">
+            <g transform="matrix(1,0,0,1,-4,3)">
+                <path d="M360.304,111.534C363.113,108.192 389.309,70.107 418.113,69.792C455.004,69.388 453.98,85.001 454,85C411.09,80.447 406.306,113.749 391,127C376.213,128.875 359.884,111.957 360.304,111.534Z" style="fill:url(#_Linear1);"/>
+            </g>
+            <path d="M387,130C363.955,129.387 356.634,111.656 343.218,92.638C330.132,74.086 315.144,42 265,42C248.667,42 218,47 196,79C177.551,105.835 180.795,160.269 198,181C212.195,198.104 235.087,219.856 272.671,207.843C285.88,203.621 300.902,195.229 318,181C308.173,174.775 295,164 295,164C295,164 280.632,185.275 257,185C187.717,184.194 202.028,62.709 261,62C318.068,61.314 316.755,172.294 387,130Z" style="fill:url(#_Linear2);"/>
+            <path d="M237,121C298.486,85.797 306.507,159.426 345.704,159.426C369.233,159.426 379.051,151.385 430,113C433.734,111.659 461,183 461,183C455.02,189.367 449.324,189.969 444,183C440.77,151.879 425.801,136.49 421,139C421,139 382.667,187.667 338,186C287.813,183.443 267.695,115.583 237,121Z" style="fill:url(#_Linear3);"/>
+        </g>
+    </g>
+    <defs>
+        <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(-38,11,-11,-38,440,80)"><stop offset="0" style="stop-color:rgb(74,62,205);stop-opacity:1"/><stop offset="1" style="stop-color:rgb(116,82,222);stop-opacity:1"/></linearGradient>
+        <linearGradient id="_Linear2" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(-104,82,-82,-104,296,85)"><stop offset="0" style="stop-color:rgb(144,96,234);stop-opacity:1"/><stop offset="1" style="stop-color:rgb(74,62,205);stop-opacity:1"/></linearGradient>
+        <linearGradient id="_Linear3" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(-222,-64,64,-222,461,183)"><stop offset="0" style="stop-color:rgb(26,188,237);stop-opacity:1"/><stop offset="1" style="stop-color:rgb(101,78,217);stop-opacity:1"/></linearGradient>
+    </defs>
+</svg>

package/docs/brand-guide/README.md

@@ -0,0 +1,107 @@
+# OSSA Brand Guide
+
+> **Version 1.0.0** | Last Updated: November 2025
+
+Official brand guidelines for the Open Standard for Scalable AI Agents (OSSA).
+
+## Table of Contents
+
+| Section | Description |
+|---------|-------------|
+| [01. Brand Overview](./01-brand-overview.md) | Mission, vision, values, positioning |
+| [02. Logo Usage](./02-logo-usage.md) | Logo variants, sizing, usage rules |
+| [03. Color Palette](./03-color-palette.md) | Brand colors, semantic colors, gradients |
+| [04. Typography](./04-typography.md) | Font families, type scale, usage guidelines |
+| [05. Voice & Tone](./05-voice-and-tone.md) | Writing style, tone variations, messaging |
+| [06. Visual Elements](./06-visual-elements.md) | Icons, buttons, spacing, animations |
+| [07. Application Examples](./07-application-examples.md) | Real-world implementation examples |
+
+## Brand at a Glance
+
+**Name:** OSSA (Open Standard for Scalable AI Agents)
+**Tagline:** "The OpenAPI for AI Agents"
+**Domain:** https://openstandardagents.org
+
+### Colors
+
+- **Primary:** Deep Purple (#4A3ECD)
+- **Secondary:** Cyan Blue (#1CB9ED)
+- **Accent:** Light Purple (#9060EA)
+- **Neutrals:** Gray scale (#F9FAFB - #111827)
+
+### Typography
+
+- **Primary:** Inter (Sans-serif)
+- **Monospace:** JetBrains Mono
+
+### Logo
+
+**Location:** `/website/public/brand/ossa-logo.svg`
+**Minimum Size:** 120px width (digital), 1 inch (print)
+
+## Core Principles
+
+1. **Open & Vendor-Neutral** - Community-driven, no vendor lock-in
+2. **Interoperable** - Common language across all frameworks
+3. **Trustworthy** - Compliance-ready, enterprise-grade
+4. **Simple & Practical** - Clear specification, production-ready
+
+## Voice
+
+**Professional, Clear, Confident, Inclusive, Practical**
+
+## Key Message
+
+**"The OpenAPI for AI Agents"**
+
+OSSA provides a universal specification standard that makes AI agents interoperable across all platforms, frameworks, and runtimes.
+
+## Quick Reference
+
+### Dos
+
+✅ Use approved color palette and gradients
+✅ Follow typography hierarchy and sizing
+✅ Respect logo clear space and minimum sizes
+✅ Write in active voice with clear language
+✅ Maintain WCAG AA accessibility (AAA preferred)
+✅ Provide working code examples
+
+### Don'ts
+
+❌ Modify logo colors or proportions
+❌ Use colors outside approved palette
+❌ Mix font families
+❌ Use exclusive language ("obviously," "simply")
+❌ Make unsubstantiated claims
+❌ Violate accessibility guidelines
+
+## Resources
+
+### Design Assets
+
+**Logo:** `/website/public/brand/ossa-logo.svg`
+**Colors:** `website/styles/_variables.scss`
+**Website:** https://openstandardagents.org
+
+### Request Full Package
+
+**Contact:** design@openstandardagents.org
+**Includes:** All logo variants, color swatches, templates
+**Formats:** SVG, PNG, AI, Figma
+
+## Support
+
+**Questions:** design@openstandardagents.org
+**Documentation:** https://openstandardagents.org/brand
+**Issues:** https://github.com/blueflyio/openstandardagents/issues
+
+## License
+
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+**Trademark:** "OSSA" and the OSSA logo are trademarks of the OSSA project.
+
+---
+
+**Ready to get started?** Pick a section above and dive in!

package/docs/comparison.md

@@ -0,0 +1,315 @@
+# OSSA Competitive Comparison Matrix
+
+## Quick Comparison
+
+| Feature | OSSA | LangChain | AutoGen | MCP | Semantic Kernel |
+|---------|------|-----------|---------|-----|-----------------|
+| **Vendor Neutral** | ✅ | ❌ | ❌ | ✅ | ❌ |
+| **Formal Standard** | ✅ | ❌ | ❌ | ✅ | ❌ |
+| **Multi-Runtime** | ✅ | ✅ | ❌ | ❌ | ✅ |
+| **Enterprise Governance** | ✅ | ❌ | ❌ | ❌ | ❌ |
+| **Compliance Ready** | ✅ | ❌ | ❌ | ❌ | ❌ |
+| **Multi-Agent Orchestration** | ✅ | ✅ | ✅ | ❌ | ✅ |
+| **Open Source** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Production Maturity** | 🟡 | ✅ | 🟡 | 🟡 | ✅ |
+| **Community Size** | 🟡 | ✅ | 🟡 | 🟡 | 🟡 |
+
+**Legend:**
+- ✅ Full support
+- 🟡 Partial/In progress
+- ❌ Not supported
+
+## Detailed Comparison
+
+### OSSA (Open Standard for AI Agents)
+
+**What it is:** Vendor-neutral specification for building portable AI agent systems
+
+**Strengths:**
+- True vendor independence—no provider lock-in
+- Built-in compliance frameworks (HIPAA, FedRAMP, SOC2)
+- Formal specification with versioning and governance
+- Multi-runtime support (Node.js, Python planned)
+- Enterprise-grade lifecycle management
+
+**Limitations:**
+- Newer project, smaller community
+- Fewer pre-built integrations than mature frameworks
+- Still building ecosystem of tools and adapters
+
+**Best for:**
+- Enterprise deployments requiring compliance
+- Organizations avoiding vendor lock-in
+- Multi-provider agent architectures
+- Regulated industries (healthcare, government, finance)
+
+---
+
+### LangChain
+
+**What it is:** Python/TypeScript framework for building LLM applications
+
+**Strengths:**
+- Large ecosystem and community
+- Extensive integrations and tools
+- Production-proven at scale
+- Rich documentation and examples
+
+**Limitations:**
+- Provider bias (OpenAI-centric design)
+- No formal compliance frameworks
+- Framework lock-in (not a standard)
+- Limited governance capabilities
+
+**Best for:**
+- Rapid prototyping
+- OpenAI-primary deployments
+- Projects not requiring strict compliance
+- Teams comfortable with framework dependencies
+
+**Choose OSSA over LangChain if:**
+- You need to switch between AI providers
+- Compliance is a requirement
+- You want a standard, not a framework
+- Vendor independence is critical
+
+---
+
+### AutoGen
+
+**What it is:** Microsoft's multi-agent conversation framework
+
+**Strengths:**
+- Strong multi-agent capabilities
+- Good for research and experimentation
+- Microsoft backing and support
+- Innovative conversation patterns
+
+**Limitations:**
+- Python-only (no multi-runtime)
+- Microsoft/Azure-centric
+- Not a formal standard
+- Limited enterprise governance
+
+**Best for:**
+- Research projects
+- Microsoft/Azure environments
+- Python-only teams
+- Multi-agent experimentation
+
+**Choose OSSA over AutoGen if:**
+- You need multi-runtime support
+- You're not in Microsoft ecosystem
+- You need formal compliance frameworks
+- You want vendor neutrality
+
+---
+
+### MCP (Model Context Protocol)
+
+**What it is:** Anthropic's protocol for connecting context to LLMs
+
+**Strengths:**
+- Formal specification
+- Vendor-neutral design
+- Good for context management
+- Growing adoption
+
+**Limitations:**
+- Context protocol only (not full agent lifecycle)
+- No multi-agent orchestration
+- No built-in governance
+- Limited to context sharing
+
+**Best for:**
+- Context management between tools
+- Anthropic Claude integrations
+- Simple context-sharing use cases
+
+**Choose OSSA over MCP if:**
+- You need full agent lifecycle management
+- You want multi-agent orchestration
+- You need enterprise governance
+- You're building complex agent systems
+
+**Use together:**
+- OSSA agents can use MCP for context management
+- Complementary, not competitive
+
+---
+
+### Semantic Kernel
+
+**What it is:** Microsoft's SDK for integrating LLMs into applications
+
+**Strengths:**
+- Microsoft backing
+- Multi-language support (.NET, Python, Java)
+- Good Azure integration
+- Enterprise features
+
+**Limitations:**
+- Microsoft-controlled (not community-driven)
+- Azure-optimized (vendor bias)
+- SDK, not a standard
+- Limited vendor independence
+
+**Best for:**
+- Microsoft/.NET shops
+- Azure-centric deployments
+- Enterprise Microsoft customers
+
+**Choose OSSA over Semantic Kernel if:**
+- You want community-driven standards
+- You need true vendor neutrality
+- You're not in Microsoft ecosystem
+- You want formal compliance frameworks
+
+---
+
+## Feature Deep-Dive
+
+### Vendor Neutral
+**Why it matters:** Avoid lock-in, maintain negotiating power, switch providers as market evolves
+
+- **OSSA**: ✅ Core design principle—no provider bias
+- **LangChain**: ❌ OpenAI-centric abstractions
+- **AutoGen**: ❌ Microsoft/Azure focus
+- **MCP**: ✅ Vendor-neutral by design
+- **Semantic Kernel**: ❌ Azure-optimized
+
+### Formal Standard
+**Why it matters:** Interoperability, long-term stability, community governance
+
+- **OSSA**: ✅ Versioned specification with governance
+- **LangChain**: ❌ Framework, not a standard
+- **AutoGen**: ❌ Research project
+- **MCP**: ✅ Formal protocol specification
+- **Semantic Kernel**: ❌ Microsoft SDK
+
+### Multi-Runtime Support
+**Why it matters:** Use best language for each component, team flexibility
+
+- **OSSA**: ✅ Node.js, Python (planned), more coming
+- **LangChain**: ✅ Python and TypeScript
+- **AutoGen**: ❌ Python only
+- **MCP**: ❌ Language-agnostic protocol, but limited implementations
+- **Semantic Kernel**: ✅ .NET, Python, Java
+
+### Enterprise Governance
+**Why it matters:** Versioning, change control, audit trails, compliance
+
+- **OSSA**: ✅ Built-in lifecycle management
+- **LangChain**: ❌ No formal governance
+- **AutoGen**: ❌ Research-focused
+- **MCP**: ❌ Protocol only
+- **Semantic Kernel**: ❌ Limited governance features
+
+### Compliance Ready
+**Why it matters:** HIPAA, FedRAMP, SOC2 requirements for production
+
+- **OSSA**: ✅ Built-in compliance frameworks
+- **LangChain**: ❌ No compliance features
+- **AutoGen**: ❌ Not compliance-focused
+- **MCP**: ❌ No compliance features
+- **Semantic Kernel**: ❌ No built-in compliance
+
+### Multi-Agent Orchestration
+**Why it matters:** Complex workflows, agent collaboration, scalability
+
+- **OSSA**: ✅ Standardized composition patterns
+- **LangChain**: ✅ Agent chains and tools
+- **AutoGen**: ✅ Strong multi-agent focus
+- **MCP**: ❌ Not designed for orchestration
+- **Semantic Kernel**: ✅ Planner and orchestration
+
+---
+
+## Use Case Mapping
+
+### Choose OSSA if you need:
+- ✅ Vendor independence and portability
+- ✅ Regulatory compliance (HIPAA, FedRAMP, SOC2)
+- ✅ Enterprise governance and lifecycle management
+- ✅ Multi-provider agent architectures
+- ✅ Formal standard with community governance
+
+### Choose LangChain if you need:
+- ✅ Rapid prototyping with rich ecosystem
+- ✅ OpenAI-primary deployments
+- ✅ Extensive pre-built integrations
+- ✅ Large community and resources
+- ❌ But accept framework lock-in
+
+### Choose AutoGen if you need:
+- ✅ Multi-agent research and experimentation
+- ✅ Python-only environment
+- ✅ Microsoft/Azure ecosystem
+- ❌ But don't need production governance
+
+### Choose MCP if you need:
+- ✅ Simple context sharing between tools
+- ✅ Anthropic Claude integration
+- ✅ Lightweight protocol
+- ❌ But don't need full agent lifecycle
+
+### Choose Semantic Kernel if you need:
+- ✅ Microsoft/.NET integration
+- ✅ Azure-optimized deployment
+- ✅ Enterprise Microsoft support
+- ❌ But accept Microsoft ecosystem lock-in
+
+---
+
+## Migration Paths
+
+### From LangChain to OSSA
+1. Map LangChain chains to OSSA agent definitions
+2. Replace provider-specific code with OSSA adapters
+3. Add compliance and governance layers
+4. Test with multiple providers
+
+**Effort:** Medium (2-4 weeks for typical application)
+
+### From AutoGen to OSSA
+1. Convert AutoGen agents to OSSA agent specs
+2. Migrate conversation patterns to OSSA orchestration
+3. Add multi-runtime support if needed
+4. Implement governance requirements
+
+**Effort:** Medium-High (3-6 weeks)
+
+### From Semantic Kernel to OSSA
+1. Extract business logic from SK abstractions
+2. Define OSSA agent specifications
+3. Replace Azure-specific code with provider-agnostic adapters
+4. Add compliance frameworks
+
+**Effort:** Medium (2-4 weeks)
+
+### Using MCP with OSSA
+- MCP and OSSA are complementary
+- Use MCP for context management within OSSA agents
+- No migration needed—integrate both
+
+---
+
+## Summary: When to Choose OSSA
+
+**Choose OSSA when:**
+1. Vendor independence is critical
+2. Compliance is required (HIPAA, FedRAMP, SOC2)
+3. You need enterprise governance
+4. You want a standard, not a framework
+5. You're building for long-term portability
+
+**Consider alternatives when:**
+1. You need rapid prototyping with rich ecosystem (→ LangChain)
+2. You're doing multi-agent research (→ AutoGen)
+3. You only need context sharing (→ MCP)
+4. You're all-in on Microsoft/.NET (→ Semantic Kernel)
+
+**The OSSA Advantage:**
+> "Build once, run anywhere—with compliance and governance built in."
+
+No other solution offers the combination of vendor neutrality, formal standards, compliance frameworks, and enterprise governance that OSSA provides.