@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/architecture/overview.md

@@ -0,0 +1,121 @@
+# Architecture Overview
+
+Understanding how OSSA works and where it fits in the AI agent ecosystem.
+
+---
+
+## What You'll Learn
+
+This architecture section provides visual maps and detailed explanations of:
+
+1. **How OSSA agents execute** - From user request to LLM response
+2. **Where OSSA fits** in your technology stack
+3. **How agents communicate** in multi-agent systems
+4. **Data flow patterns** across the ecosystem
+
+---
+
+## Architecture Topics
+
+### [Execution Flow](execution-flow)
+Detailed sequence diagrams showing how a user request flows through an OSSA agent:
+- User interaction patterns
+- Agent orchestration lifecycle
+- LLM integration points
+- Tool execution and responses
+
+**Learn**: How does a request move through an OSSA agent?
+
+---
+
+### [Stack Integration](stack-integration)
+Layer-by-layer view of where OSSA fits in your infrastructure:
+- Application layer integration
+- Runtime environments
+- OSSA specification layer
+- Tools, APIs, and external services
+- Infrastructure deployment options
+
+**Learn**: Where does OSSA live in my architecture?
+
+---
+
+### [Multi-Agent Systems](multi-agent-systems)
+Agent-to-agent communication patterns using OSSA manifests:
+- Agent discovery mechanisms
+- Inter-agent messaging protocols
+- Coordination and orchestration patterns
+- Distributed agent topologies
+
+**Learn**: How do multiple OSSA agents work together?
+
+---
+
+## Why Architecture Matters
+
+Just like OpenAPI provides a standard contract for REST APIs, OSSA provides a standard contract for AI agents. Understanding the architecture helps you:
+
+- ✅ **Design better agents** - Understand boundaries and capabilities
+- ✅ **Integrate seamlessly** - Know where OSSA fits in your stack
+- ✅ **Scale effectively** - Plan for multi-agent systems
+- ✅ **Debug faster** - Trace data flow through components
+- ✅ **Deploy confidently** - Understand runtime requirements
+
+---
+
+## OSSA Architecture Principles
+
+### 1. Specification-Driven
+OSSA defines the **contract**, not the implementation. Your runtime handles the execution.
+
+### 2. Layer Separation
+Clear boundaries between:
+- Application logic
+- Agent runtime
+- OSSA specification layer
+- External tools/APIs
+- Infrastructure
+
+### 3. Framework Agnostic
+OSSA doesn't care if you use:
+- LangChain, LlamaIndex, Anthropic SDK, OpenAI SDK
+- Python, TypeScript, Go, Rust
+- Kubernetes, Docker, serverless, on-premise
+
+### 4. Runtime Independent
+Deploy OSSA agents anywhere:
+- Cloud (AWS, GCP, Azure)
+- Edge computing
+- On-premise data centers
+- Hybrid environments
+
+---
+
+## Quick Reference
+
+| Topic | Use Case | Audience |
+|-------|----------|----------|
+| **Execution Flow** | Understanding agent lifecycle | Developers, Architects |
+| **Stack Integration** | Planning deployments | Architects, Platform Engineers |
+| **Multi-Agent Systems** | Designing agent networks | Senior Developers, Architects |
+
+---
+
+## Related Documentation
+
+- [Specification](/docs/specification) - Technical details of the OSSA spec
+- [Schema Reference](/docs/schema-reference) - Complete schema documentation
+- [Ecosystem Overview](/docs/ecosystem/overview) - Framework integrations
+- [Migration Guides](/docs/migration-guides/langchain-to-ossa) - Real-world migration examples
+
+---
+
+## Visual Learning Path
+
+1. **Start here** → [Execution Flow](execution-flow) - See how a single agent works
+2. **Then** → [Stack Integration](stack-integration) - Understand where OSSA fits
+3. **Finally** → [Multi-Agent Systems](multi-agent-systems) - Learn agent coordination
+
+---
+
+**Next**: [Execution Flow Diagram](execution-flow) - See how requests flow through OSSA agents

package/website/content/docs/architecture/stack-integration.md

@@ -0,0 +1,461 @@
+# Stack Integration Architecture
+
+Where OSSA fits in your technology stack and infrastructure.
+
+---
+
+## Overview
+
+This page shows how OSSA integrates into modern application architectures, from frontend applications down to infrastructure. OSSA sits as a **specification layer** between your application and the agent runtime.
+
+---
+
+## Complete Stack Diagram
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        WebApp[Web Application]
+        MobileApp[Mobile App]
+        CLI[CLI Tools]
+        API[REST/GraphQL API]
+    end
+
+    subgraph "Agent Runtime Layer"
+        Runtime[Agent Runtime<br/>LangChain | LlamaIndex<br/>Anthropic SDK | OpenAI SDK<br/>Custom Runtime]
+        Orchestrator[Agent Orchestrator]
+        Memory[Memory Store<br/>Redis | PostgreSQL]
+    end
+
+    subgraph "OSSA Specification Layer"
+        Manifest[OSSA Manifests<br/>agent.ossa.yaml]
+        Schema[JSON Schema<br/>v0.2.x]
+        CLI_Tool[OSSA CLI<br/>Validation]
+        Registry[Agent Registry]
+    end
+
+    subgraph "Tools & APIs Layer"
+        Functions[Function Tools<br/>Python | TypeScript]
+        REST[REST APIs<br/>Weather | CRM]
+        Database[Databases<br/>PostgreSQL | MongoDB]
+        Vector[Vector DBs<br/>Pinecone | Weaviate]
+    end
+
+    subgraph "LLM Provider Layer"
+        OpenAI[OpenAI<br/>GPT-3.5/4]
+        Anthropic[Anthropic<br/>Claude]
+        Other[Other Providers<br/>Cohere | Mistral]
+    end
+
+    subgraph "Infrastructure Layer"
+        K8s[Kubernetes]
+        Docker[Docker]
+        Serverless[Serverless<br/>Lambda | Cloud Run]
+        OnPrem[On-Premise]
+    end
+
+    WebApp --> Runtime
+    MobileApp --> Runtime
+    CLI --> Runtime
+    API --> Runtime
+
+    Runtime --> Orchestrator
+    Runtime --> Memory
+
+    Orchestrator --> Manifest
+    Manifest --> Schema
+    Manifest --> CLI_Tool
+    Manifest --> Registry
+
+    Orchestrator --> Functions
+    Orchestrator --> REST
+    Orchestrator --> Database
+    Orchestrator --> Vector
+
+    Orchestrator --> OpenAI
+    Orchestrator --> Anthropic
+    Orchestrator --> Other
+
+    Runtime --> K8s
+    Runtime --> Docker
+    Runtime --> Serverless
+    Runtime --> OnPrem
+
+    style Manifest fill:#4A90E2,stroke:#333,stroke-width:4px,color:#fff
+    style Schema fill:#4A90E2,stroke:#333,stroke-width:4px,color:#fff
+    style CLI_Tool fill:#4A90E2,stroke:#333,stroke-width:4px,color:#fff
+    style Registry fill:#4A90E2,stroke:#333,stroke-width:4px,color:#fff
+```
+
+---
+
+## Layer-by-Layer Breakdown
+
+### 1. Application Layer
+**What it is:** Your user-facing applications
+
+**Components:**
+- Web applications (React, Vue, Angular)
+- Mobile apps (iOS, Android, React Native)
+- CLI tools (Node.js, Python scripts)
+- REST/GraphQL APIs
+
+**OSSA's role:**
+- ❌ OSSA does NOT interact with this layer directly
+- ✅ Applications call your agent runtime (which uses OSSA)
+
+**Example:**
+```typescript
+// Your frontend code
+const response = await fetch('/api/agent', {
+  method: 'POST',
+  body: JSON.stringify({ message: 'What is the weather?' })
+});
+```
+
+---
+
+### 2. Agent Runtime Layer
+**What it is:** The execution environment for your agents
+
+**Components:**
+- **Agent Runtime**: Framework that executes agents (LangChain, LlamaIndex, custom)
+- **Agent Orchestrator**: Coordinates agent execution lifecycle
+- **Memory Store**: Conversation history, context (Redis, PostgreSQL)
+
+**OSSA's role:**
+- ✅ Runtime reads OSSA manifests to configure agents
+- ✅ Orchestrator uses OSSA specs to determine execution flow
+- ✅ Memory rules defined in OSSA manifest
+
+**Example Runtime Configuration:**
+```python
+# Runtime loads OSSA manifest
+from ossa import load_agent
+
+agent = load_agent("agent.ossa.yaml")
+response = agent.run(user_message="Hello")
+```
+
+---
+
+### 3. OSSA Specification Layer ⭐
+**What it is:** The standard layer - this is where OSSA lives
+
+**Components:**
+- **OSSA Manifests**: YAML/JSON files defining agents
+- **JSON Schema**: Validation schema (v0.2.x)
+- **OSSA CLI**: Validation and generation tools
+- **Agent Registry**: Discovery and versioning
+
+**OSSA's role:**
+- ✅ **This IS OSSA** - the specification layer
+- ✅ Defines the contract between application and runtime
+- ✅ Provides validation, versioning, and discovery
+
+**Example Manifest:**
+```yaml
+apiVersion: ossa/v0.2.x
+kind: Agent
+metadata:
+  name: weather-agent
+  version: 1.0.0
+spec:
+  role: You are a weather assistant
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+  tools:
+    - type: function
+      name: get_weather
+```
+
+---
+
+### 4. Tools & APIs Layer
+**What it is:** External services agents can call
+
+**Components:**
+- **Function Tools**: Custom Python/TypeScript functions
+- **REST APIs**: Third-party services (Weather, CRM, etc.)
+- **Databases**: Structured data storage
+- **Vector Databases**: Semantic search, RAG
+
+**OSSA's role:**
+- ✅ Tool schemas defined in OSSA manifest (`spec.tools[]`)
+- ✅ Execution constraints specified in manifest
+- ✅ Error handling rules defined
+
+**Example Tool Definition:**
+```yaml
+tools:
+  - type: function
+    name: query_database
+    description: Query PostgreSQL database
+    parameters:
+      type: object
+      properties:
+        query:
+          type: string
+    timeout: 5000
+    retry:
+      maxAttempts: 3
+```
+
+---
+
+### 5. LLM Provider Layer
+**What it is:** AI model APIs
+
+**Components:**
+- OpenAI (GPT-3.5, GPT-4)
+- Anthropic (Claude)
+- Other providers (Cohere, Mistral, etc.)
+
+**OSSA's role:**
+- ✅ Provider specified in manifest (`spec.llm.provider`)
+- ✅ Model specified in manifest (`spec.llm.model`)
+- ✅ Configuration (temperature, max_tokens) defined
+
+**Example LLM Config:**
+```yaml
+spec:
+  llm:
+    provider: anthropic
+    model: claude-3-sonnet-20240229
+    temperature: 0.7
+    maxTokens: 1000
+```
+
+---
+
+### 6. Infrastructure Layer
+**What it is:** Where your agent runtime is deployed
+
+**Components:**
+- Kubernetes clusters
+- Docker containers
+- Serverless functions (Lambda, Cloud Run)
+- On-premise servers
+
+**OSSA's role:**
+- ❌ OSSA does NOT define infrastructure
+- ✅ OSSA manifests are portable across ANY infrastructure
+- ✅ Deploy the same manifest to K8s, Docker, serverless, etc.
+
+**Deployment Examples:**
+```bash
+# Kubernetes
+kubectl apply -f agent-deployment.yaml
+
+# Docker
+docker run -v ./agent.ossa.yaml:/config/agent.ossa.yaml my-agent-runtime
+
+# Serverless (AWS Lambda)
+aws lambda update-function-code --function-name my-agent \
+  --zip-file fileb://agent.zip
+```
+
+---
+
+## Integration Patterns
+
+### Pattern 1: Web Application + OSSA Agent
+
+```mermaid
+graph LR
+    User[User Browser] --> React[React Frontend]
+    React --> API[Express API]
+    API --> Runtime[Agent Runtime]
+    Runtime --> Manifest[OSSA Manifest]
+    Runtime --> OpenAI[OpenAI API]
+
+    style Manifest fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff
+```
+
+**Use case:** Chat interface for customer support
+
+**OSSA manifest:** Defines support agent role, tools (CRM lookup, ticket creation)
+
+---
+
+### Pattern 2: Microservices + Multi-Agent System
+
+```mermaid
+graph TB
+    Gateway[API Gateway] --> AgentA[Customer Agent]
+    Gateway --> AgentB[Sales Agent]
+    Gateway --> AgentC[Support Agent]
+
+    AgentA --> ManifestA[agent-customer.ossa.yaml]
+    AgentB --> ManifestB[agent-sales.ossa.yaml]
+    AgentC --> ManifestC[agent-support.ossa.yaml]
+
+    AgentA --> DB[(Shared DB)]
+    AgentB --> DB
+    AgentC --> DB
+
+    style ManifestA fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff
+    style ManifestB fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff
+    style ManifestC fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff
+```
+
+**Use case:** Specialized agents for different business functions
+
+**OSSA manifests:** Each agent has its own manifest with specialized tools
+
+---
+
+### Pattern 3: Serverless Event-Driven Architecture
+
+```mermaid
+graph LR
+    Event[Event Source<br/>S3 | SQS | Webhook] --> Lambda[Lambda Function]
+    Lambda --> Runtime[Agent Runtime]
+    Runtime --> Manifest[OSSA Manifest]
+    Runtime --> Tools[External APIs]
+    Lambda --> Result[Result Queue]
+
+    style Manifest fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff
+```
+
+**Use case:** Document processing agent triggered by file uploads
+
+**OSSA manifest:** Defines document analysis tools and LLM configuration
+
+---
+
+## Where OSSA Sits: Quick Reference
+
+| Layer | OSSA's Role | Examples |
+|-------|-------------|----------|
+| **Application** | Not involved | React, Vue, Mobile Apps |
+| **Agent Runtime** | **Configuration source** | LangChain, LlamaIndex, Custom |
+| **OSSA Layer** | **This IS OSSA** | Manifests, Schema, CLI |
+| **Tools/APIs** | **Schema definition** | REST APIs, Functions, DBs |
+| **LLM Provider** | **Provider selection** | OpenAI, Anthropic, Cohere |
+| **Infrastructure** | Not involved (portable) | K8s, Docker, Serverless |
+
+---
+
+## Technology Stack Examples
+
+### Stack 1: Modern Web App
+```
+Frontend:      React + TypeScript
+API:           Node.js + Express
+Runtime:       LangChain (TypeScript)
+OSSA:          agent.ossa.yaml ← OSSA HERE
+LLM:           OpenAI GPT-4
+Infrastructure: Kubernetes
+```
+
+### Stack 2: Enterprise Python
+```
+Frontend:      Internal Dashboard
+API:           FastAPI
+Runtime:       LlamaIndex (Python)
+OSSA:          agent.ossa.yaml ← OSSA HERE
+LLM:           Anthropic Claude
+Infrastructure: AWS Lambda
+```
+
+### Stack 3: On-Premise
+```
+Frontend:      Custom Java App
+API:           Spring Boot
+Runtime:       Custom Runtime (Go)
+OSSA:          agent.ossa.yaml ← OSSA HERE
+LLM:           Self-hosted (Ollama)
+Infrastructure: On-premise servers
+```
+
+**Notice:** OSSA is the same in all stacks - just the manifest file!
+
+---
+
+## Key Integration Points
+
+### 1. Agent Initialization
+```python
+# Runtime loads OSSA manifest at startup
+agent = load_agent("agent.ossa.yaml")
+```
+
+### 2. Request Processing
+```python
+# Runtime uses OSSA config to process requests
+response = agent.run(
+    message=user_input,
+    # OSSA manifest defines:
+    # - role/system prompt
+    # - available tools
+    # - LLM provider/model
+)
+```
+
+### 3. Tool Execution
+```python
+# Runtime validates tools against OSSA schema
+if tool_name in agent.manifest.tools:
+    result = execute_tool(tool_name, args)
+```
+
+---
+
+## Migration Paths
+
+### From Framework-Specific to OSSA
+
+```mermaid
+graph LR
+    A[LangChain Agent<br/>Python Code] --> B[Extract Config]
+    B --> C[Generate OSSA Manifest]
+    C --> D[Update Runtime<br/>to Load Manifest]
+    D --> E[Deploy with OSSA]
+
+    style C fill:#4A90E2,stroke:#333,stroke-width:2px,color:#fff
+```
+
+**Steps:**
+1. Extract agent configuration from code
+2. Generate OSSA manifest using CLI: `ossa generate`
+3. Update runtime to load manifest instead of hardcoded config
+4. Deploy! Same runtime, now OSSA-compliant
+
+---
+
+## Benefits of This Architecture
+
+### Separation of Concerns
+- **Application Layer**: User experience
+- **OSSA Layer**: Agent contract
+- **Runtime Layer**: Execution
+- **Infrastructure Layer**: Deployment
+
+### Portability
+Move the same OSSA manifest across:
+- Different runtimes (LangChain → LlamaIndex)
+- Different infrastructures (K8s → Serverless)
+- Different teams/organizations
+
+### Flexibility
+Change any layer without affecting others:
+- Swap LLM providers (OpenAI → Anthropic)
+- Change runtimes (Python → TypeScript)
+- Migrate infrastructure (Docker → K8s)
+
+**OSSA manifest stays the same!**
+
+---
+
+## Related Documentation
+
+- [Execution Flow](execution-flow) - How requests flow through OSSA agents
+- [Specification](/docs/specification) - Deployment guides
+- [Ecosystem Overview](/docs/ecosystem/overview) - Real-world examples
+- [Multi-Agent Systems](multi-agent-systems) - Agent-to-agent communication
+
+---
+
+**Next**: [Multi-Agent Systems](multi-agent-systems) - See how multiple OSSA agents coordinate