@bluefly/openstandardagents 0.2.5-RC → 0.2.8

package/website/content/docs/schema-reference/constraints.md

@@ -1,543 +0,0 @@
----
-title: "Constraints"
-description: "Cost, performance, and resource constraints configuration"
-weight: 7
----
-
-# Constraints Object
-
-The `constraints` object in `spec.constraints` defines operational limits for cost, performance, and resource usage. Constraints prevent runaway costs, ensure SLAs, and manage resource allocation.
-
-## Field Reference
-
-| Field Name | Type | Required | Description |
-|------------|------|----------|-------------|
-| `cost` | [Cost](#cost-constraints) | No | Cost and token usage limits |
-| `performance` | [Performance](#performance-constraints) | No | Latency, concurrency, and timeout settings |
-| `resources` | [Resources](#resource-constraints) | No | CPU, memory, and GPU allocation (Kubernetes format) |
-
-## Cost Constraints
-
-Cost constraints prevent excessive LLM API usage and spending.
-
-| Field Name | Type | Required | Description |
-|------------|------|----------|-------------|
-| `maxTokensPerDay` | integer | No | Maximum tokens allowed per day (input + output combined). Minimum: 0 |
-| `maxTokensPerRequest` | integer | No | Maximum tokens per individual request. Minimum: 0 |
-| `maxCostPerDay` | number | No | Maximum cost per day in specified currency. Minimum: 0 |
-| `currency` | string | No | ISO 4217 currency code (3 uppercase letters). Default: `USD` |
-
-### Examples
-
-```yaml
-# Moderate daily limits
-constraints:
-  cost:
-    maxTokensPerDay: 1000000      # 1M tokens/day
-    maxTokensPerRequest: 10000    # 10K tokens/request
-    maxCostPerDay: 50.0          # $50/day
-    currency: USD
-
-# High-volume agent
-constraints:
-  cost:
-    maxTokensPerDay: 50000000     # 50M tokens/day
-    maxTokensPerRequest: 100000   # 100K tokens/request
-    maxCostPerDay: 500.0
-    currency: USD
-
-# Experimental/testing
-constraints:
-  cost:
-    maxTokensPerDay: 100000       # 100K tokens/day
-    maxCostPerDay: 5.0
-    currency: USD
-
-# European deployment
-constraints:
-  cost:
-    maxTokensPerDay: 5000000
-    maxCostPerDay: 200.0
-    currency: EUR
-```
-
-### Cost Calculation
-
-Cost tracking varies by provider:
-
-**OpenAI:**
-```yaml
-# GPT-4o: $2.50/1M input, $10.00/1M output
-constraints:
-  cost:
-    maxTokensPerDay: 1000000
-    maxCostPerDay: 10.0
-```
-
-**Anthropic:**
-```yaml
-# Claude 3.5 Sonnet: $3.00/1M input, $15.00/1M output
-constraints:
-  cost:
-    maxTokensPerDay: 1000000
-    maxCostPerDay: 15.0
-```
-
-**Note:** Platforms typically estimate cost based on provider pricing. For precise cost control, use both token and cost limits.
-
-## Performance Constraints
-
-Performance constraints ensure latency SLAs and prevent resource exhaustion.
-
-| Field Name | Type | Required | Description |
-|------------|------|----------|-------------|
-| `maxLatencySeconds` | number | No | Maximum acceptable latency per request in seconds. Minimum: 0 |
-| `maxConcurrentRequests` | integer | No | Maximum concurrent requests the agent can handle. Minimum: 1 |
-| `timeoutSeconds` | number | No | Request timeout in seconds. Minimum: 0 |
-
-### Examples
-
-```yaml
-# Low-latency requirements (chatbot)
-constraints:
-  performance:
-    maxLatencySeconds: 3
-    maxConcurrentRequests: 100
-    timeoutSeconds: 10
-
-# Batch processing
-constraints:
-  performance:
-    maxLatencySeconds: 60
-    maxConcurrentRequests: 10
-    timeoutSeconds: 300
-
-# High-throughput
-constraints:
-  performance:
-    maxLatencySeconds: 10
-    maxConcurrentRequests: 1000
-    timeoutSeconds: 30
-
-# Background tasks
-constraints:
-  performance:
-    maxLatencySeconds: 300
-    maxConcurrentRequests: 5
-    timeoutSeconds: 3600
-```
-
-### Latency vs. Timeout
-
-- **maxLatencySeconds:** Expected/desired latency. Platform may log warnings if exceeded.
-- **timeoutSeconds:** Hard cutoff. Requests exceeding timeout are terminated.
-
-```yaml
-constraints:
-  performance:
-    maxLatencySeconds: 5      # Warn if response takes > 5s
-    timeoutSeconds: 30        # Kill request after 30s
-```
-
-## Resource Constraints
-
-Resource constraints define CPU, memory, and GPU allocation. Uses Kubernetes resource format.
-
-| Field Name | Type | Required | Description |
-|------------|------|----------|-------------|
-| `cpu` | string | No | CPU limit in Kubernetes format. Examples: `100m`, `1`, `2.5` |
-| `memory` | string | No | Memory limit in Kubernetes format. Examples: `128Mi`, `1Gi`, `4Gi` |
-| `gpu` | string | No | GPU requirement (format varies by platform) |
-
-### CPU Format
-
-**Millicores (`m`):**
-```yaml
-resources:
-  cpu: "100m"    # 0.1 CPU core
-  cpu: "500m"    # 0.5 CPU core
-  cpu: "1000m"   # 1 CPU core
-```
-
-**Cores (integer or decimal):**
-```yaml
-resources:
-  cpu: "1"       # 1 CPU core
-  cpu: "2"       # 2 CPU cores
-  cpu: "0.5"     # 0.5 CPU core
-  cpu: "4.5"     # 4.5 CPU cores
-```
-
-### Memory Format
-
-**Mebibytes (`Mi`):**
-```yaml
-resources:
-  memory: "128Mi"   # 128 MiB
-  memory: "512Mi"   # 512 MiB
-  memory: "1024Mi"  # 1 GiB
-```
-
-**Gibibytes (`Gi`):**
-```yaml
-resources:
-  memory: "1Gi"     # 1 GiB
-  memory: "2Gi"     # 2 GiB
-  memory: "16Gi"    # 16 GiB
-```
-
-**Other units:**
-```yaml
-resources:
-  memory: "1000M"   # 1000 MB (decimal)
-  memory: "1G"      # 1 GB (decimal)
-```
-
-### GPU Requirement
-
-GPU format is platform-specific:
-
-```yaml
-# NVIDIA GPU count
-resources:
-  gpu: "1"
-
-# Specific GPU type
-resources:
-  gpu: "nvidia-tesla-v100"
-
-# GPU memory
-resources:
-  gpu: "16Gi"
-```
-
-### Resource Examples
-
-```yaml
-# Minimal (lightweight agent)
-constraints:
-  resources:
-    cpu: "100m"
-    memory: "128Mi"
-
-# Small (chatbot)
-constraints:
-  resources:
-    cpu: "500m"
-    memory: "512Mi"
-
-# Medium (code analysis)
-constraints:
-  resources:
-    cpu: "1"
-    memory: "2Gi"
-
-# Large (data processing)
-constraints:
-  resources:
-    cpu: "4"
-    memory: "8Gi"
-
-# GPU workload
-constraints:
-  resources:
-    cpu: "8"
-    memory: "32Gi"
-    gpu: "1"
-```
-
-## Complete Examples
-
-### Production Chatbot
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: customer-chatbot
-  version: 1.0.0
-spec:
-  role: You are a customer support chatbot.
-
-  llm:
-    provider: anthropic
-    model: claude-3-5-haiku-20241022
-    temperature: 0.7
-    maxTokens: 1024
-
-  constraints:
-    cost:
-      maxTokensPerDay: 10000000      # 10M tokens/day
-      maxTokensPerRequest: 2048      # 2K tokens/request
-      maxCostPerDay: 100.0
-      currency: USD
-    performance:
-      maxLatencySeconds: 3           # Fast responses
-      maxConcurrentRequests: 500     # High throughput
-      timeoutSeconds: 10
-    resources:
-      cpu: "2"
-      memory: "4Gi"
-```
-
-### Background Data Analyzer
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: data-analyzer
-  version: 1.5.0
-spec:
-  role: You are a data analysis specialist.
-
-  llm:
-    provider: openai
-    model: gpt-4o
-    temperature: 0.2
-    maxTokens: 8192
-
-  constraints:
-    cost:
-      maxTokensPerDay: 50000000      # 50M tokens/day
-      maxCostPerDay: 500.0
-      currency: USD
-    performance:
-      maxLatencySeconds: 60          # Not time-critical
-      maxConcurrentRequests: 10      # Batch processing
-      timeoutSeconds: 600            # 10 minute timeout
-    resources:
-      cpu: "4"
-      memory: "16Gi"
-```
-
-### Development/Testing Agent
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: dev-assistant
-  version: 0.1.0
-spec:
-  role: Development and testing assistant.
-
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-
-  constraints:
-    cost:
-      maxTokensPerDay: 100000        # Limited for testing
-      maxCostPerDay: 5.0
-      currency: USD
-    performance:
-      maxLatencySeconds: 10
-      maxConcurrentRequests: 5
-      timeoutSeconds: 30
-    resources:
-      cpu: "500m"
-      memory: "1Gi"
-```
-
-### High-Performance Code Generator
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: code-generator
-  version: 2.0.0
-spec:
-  role: You are an expert code generator.
-
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-    temperature: 0.2
-    maxTokens: 8192
-
-  constraints:
-    cost:
-      maxTokensPerDay: 100000000     # 100M tokens/day
-      maxTokensPerRequest: 16384     # Long responses
-      maxCostPerDay: 1000.0
-      currency: USD
-    performance:
-      maxLatencySeconds: 15
-      maxConcurrentRequests: 100
-      timeoutSeconds: 60
-    resources:
-      cpu: "8"
-      memory: "32Gi"
-```
-
-### Cost-Optimized Agent
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: budget-agent
-  version: 1.0.0
-spec:
-  role: Cost-optimized assistant.
-
-  llm:
-    provider: anthropic
-    model: claude-3-5-haiku-20241022  # Cheapest model
-    temperature: 0.5
-    maxTokens: 512                    # Short responses
-
-  constraints:
-    cost:
-      maxTokensPerDay: 500000         # Tight limit
-      maxTokensPerRequest: 1024
-      maxCostPerDay: 5.0              # Low budget
-      currency: USD
-    performance:
-      maxLatencySeconds: 5
-      maxConcurrentRequests: 50
-      timeoutSeconds: 15
-    resources:
-      cpu: "250m"                     # Minimal resources
-      memory: "256Mi"
-```
-
-## Multi-Currency Support
-
-```yaml
-# United States
-constraints:
-  cost:
-    maxCostPerDay: 100.0
-    currency: USD
-
-# European Union
-constraints:
-  cost:
-    maxCostPerDay: 90.0
-    currency: EUR
-
-# United Kingdom
-constraints:
-  cost:
-    maxCostPerDay: 80.0
-    currency: GBP
-
-# Canada
-constraints:
-  cost:
-    maxCostPerDay: 135.0
-    currency: CAD
-```
-
-**Currency validation:**
-- Must be 3 uppercase letters
-- Should be valid ISO 4217 code
-- Platform converts to provider's billing currency
-
-## Constraint Enforcement
-
-How constraints are enforced varies by platform:
-
-### Cost Constraints
-- **Soft limits:** Log warnings, continue operation
-- **Hard limits:** Reject new requests when limit reached
-- **Reset period:** Typically 24 hours from first request
-
-### Performance Constraints
-- **maxLatencySeconds:** Monitoring/alerting threshold
-- **maxConcurrentRequests:** Queue or reject excess requests
-- **timeoutSeconds:** Hard cutoff, terminate request
-
-### Resource Constraints
-- **Kubernetes:** Enforced by kubelet
-- **Docker:** Enforced by container runtime
-- **Serverless:** Enforced by platform
-
-## Best Practices
-
-1. **Set realistic limits** - Based on expected usage patterns
-2. **Monitor regularly** - Track actual usage vs. constraints
-3. **Start conservative** - Tighten constraints after observing usage
-4. **Account for spikes** - Set limits above normal usage
-5. **Use both cost metrics** - Tokens AND currency for better control
-6. **Match timeout to task** - Long-running tasks need higher timeouts
-7. **Resource padding** - Add 20-30% buffer to resource requests
-8. **Test limits** - Validate constraints work as expected
-9. **Alert on limits** - Monitor constraint violations
-10. **Document choices** - Explain constraint rationale in comments
-
-## Common Constraint Patterns
-
-### High-Volume Low-Cost
-
-```yaml
-constraints:
-  cost:
-    maxTokensPerDay: 100000000
-    maxCostPerDay: 100.0
-  performance:
-    maxConcurrentRequests: 1000
-  resources:
-    cpu: "4"
-    memory: "8Gi"
-```
-
-### Low-Volume High-Quality
-
-```yaml
-constraints:
-  cost:
-    maxTokensPerDay: 1000000
-    maxCostPerDay: 200.0
-  performance:
-    maxLatencySeconds: 5
-    maxConcurrentRequests: 10
-  resources:
-    cpu: "2"
-    memory: "4Gi"
-```
-
-### Batch Processing
-
-```yaml
-constraints:
-  cost:
-    maxTokensPerDay: 50000000
-    maxCostPerDay: 500.0
-  performance:
-    maxLatencySeconds: 300
-    timeoutSeconds: 3600
-    maxConcurrentRequests: 5
-  resources:
-    cpu: "8"
-    memory: "32Gi"
-```
-
-## Validation
-
-All constraint fields are optional.
-
-**Numeric validation:**
-- All numeric values must be >= 0
-- `maxConcurrentRequests` minimum: 1
-- `currency` pattern: `^[A-Z]{3}$`
-
-**Resource format:**
-- `cpu`: Kubernetes CPU format
-- `memory`: Kubernetes memory format
-- `gpu`: Platform-specific format
-
-## Related Objects
-
-- [Agent Spec](./agent-spec.md) - Parent object containing constraints
-- [LLM Configuration](./llm-config.md) - Model configuration affecting cost
-- [Observability](./observability.md) - Monitoring constraint violations
-- [Autonomy](./autonomy.md) - Action limits complement constraints
-
-## See Also
-
-- [Kubernetes Resource Management](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/)
-- [LLM Pricing Calculators](https://artificialanalysis.ai/models)

package/website/content/docs/schema-reference/index.md

@@ -1,176 +0,0 @@
----
-title: "Schema Reference"
-description: "Complete reference documentation for the OSSA v0.2.x Agent Manifest Schema"
-weight: 50
----
-
-# OSSA Schema Reference
-
-Complete reference documentation for the Open Standard for Scalable Agents (OSSA) v0.2.x schema.
-
-The OSSA schema provides a declarative, framework-agnostic way to define AI agents with full portability across platforms and orchestration frameworks.
-
-## Schema Overview
-
-The OSSA manifest is a JSON/YAML document that defines:
-
-- **Agent metadata** - Name, version, labels, and annotations
-- **Agent specification** - Role, LLM configuration, tools, and capabilities
-- **Autonomy settings** - Decision-making level and approval requirements
-- **Constraints** - Cost, performance, and resource limits
-- **Observability** - Tracing, metrics, and logging configuration
-- **Framework extensions** - Integration with kagent, BuildKit, Drupal, LibreChat, and 14+ other frameworks
-
-## Schema Version
-
-```yaml
-apiVersion: ossa/v0.2.x
-```
-
-The current stable version is `ossa/v0.2.x` (v0.2.2, v0.2.3, v0.2.4+). The schema also supports `ossa/v1` for forward compatibility.
-
-## Schema Components
-
-### Core Objects
-
-- [**OSSA Manifest**](./ossa-manifest.md) - Root manifest object with metadata and spec
-- [**Agent Spec**](./agent-spec.md) - Agent specification including role, LLM, and tools
-- [**LLM Configuration**](./llm-config.md) - Language model provider and parameters
-- [**Tools**](./tools.md) - Tool definitions for MCP, Kubernetes, HTTP, and custom integrations
-
-### Configuration Objects
-
-- [**Taxonomy**](./taxonomy.md) - Agent domain, subdomain, and capability classification
-- [**Autonomy**](./autonomy.md) - Decision-making level and action controls
-- [**Constraints**](./constraints.md) - Cost, performance, and resource constraints
-- [**Observability**](./observability.md) - Tracing, metrics, and logging
-
-### Framework Extensions
-
-- [**kagent Extension**](./extensions/kagent.md) - Kubernetes-native agent deployment
-- [**BuildKit Extension**](./extensions/buildkit.md) - Agent BuildKit orchestration
-- [**Drupal Extension**](./extensions/drupal.md) - Drupal LLM Platform integration
-- [**LibreChat Extension**](./extensions/librechat.md) - LibreChat integration
-- [**MCP Extension**](./extensions/mcp.md) - Model Context Protocol servers
-- [**LangChain Extension**](./extensions/langchain.md) - LangChain framework
-- [**CrewAI Extension**](./extensions/crewai.md) - CrewAI multi-agent framework
-- [**OpenAI Agents Extension**](./extensions/openai-agents.md) - OpenAI Agents SDK
-- [**Cursor Extension**](./extensions/cursor.md) - Cursor IDE integration
-- [**Langflow Extension**](./extensions/langflow.md) - Langflow workflow orchestration
-- [**AutoGen Extension**](./extensions/autogen.md) - Microsoft AutoGen
-- [**Vercel AI Extension**](./extensions/vercel-ai.md) - Vercel AI SDK
-- [**LlamaIndex Extension**](./extensions/llamaindex.md) - LlamaIndex RAG framework
-- [**LangGraph Extension**](./extensions/langgraph.md) - LangGraph state machines
-- [**Anthropic Extension**](./extensions/anthropic.md) - Anthropic Claude API
-
-## Quick Example
-
-```yaml
-apiVersion: ossa/v0.2.x
-kind: Agent
-metadata:
-  name: code-reviewer
-  version: 1.0.0
-  description: Automated code review agent
-  labels:
-    domain: development
-    capability: code-review
-spec:
-  taxonomy:
-    domain: development
-    subdomain: quality-assurance
-    capability: code-review
-  role: |
-    You are a code review specialist. Analyze code for:
-    - Security vulnerabilities
-    - Performance issues
-    - Best practices adherence
-    - Code quality and maintainability
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-    temperature: 0.3
-    maxTokens: 4096
-  tools:
-    - type: mcp
-      server: filesystem
-      capabilities:
-        - read_file
-        - list_directory
-    - type: mcp
-      server: git
-      capabilities:
-        - git_diff
-        - git_log
-  autonomy:
-    level: supervised
-    approval_required: false
-    allowed_actions:
-      - read_code
-      - analyze_security
-      - generate_report
-  constraints:
-    cost:
-      maxTokensPerDay: 1000000
-      maxCostPerDay: 50.0
-      currency: USD
-    performance:
-      maxLatencySeconds: 30
-      timeoutSeconds: 120
-  observability:
-    tracing:
-      enabled: true
-      exporter: otlp
-    metrics:
-      enabled: true
-      exporter: prometheus
-    logging:
-      level: info
-      format: json
-```
-
-## Validation
-
-All OSSA manifests must conform to the JSON Schema:
-
-```
-https://openstandardagents.org/schemas/v0.2.x/agent.json
-```
-
-Use the schema for validation in your tools and editors:
-
-**VSCode/Cursor:**
-```json
-{
-  "$schema": "https://openstandardagents.org/schemas/v0.2.x/agent.json"
-}
-```
-
-**Command-line validation:**
-```bash
-ossa validate manifest.json
-```
-
-## Framework Compatibility
-
-The OSSA schema is designed for framework-agnostic portability. The same manifest can be deployed to:
-
-- **kagent.dev** - Kubernetes-native agent platform
-- **Agent BuildKit** - Multi-runtime orchestration
-- **Drupal LLM Platform** - Drupal-based agent management
-- **LibreChat** - Open-source chat interface
-- **LangChain, CrewAI, AutoGen** - Python agent frameworks
-- **OpenAI Agents SDK** - Official OpenAI agent runtime
-- **Cursor, Continue** - IDE-integrated coding agents
-- **Vercel AI SDK** - Edge/Node.js deployment
-- **LlamaIndex, LangGraph** - RAG and state machine frameworks
-
-See the [Extensions](./extensions/) section for framework-specific configuration.
-
-## Additional Resources
-
-- [OSSA Specification](/docs/)
-- [Getting Started Guide](/docs/getting-started/)
-- [Examples](/docs/examples/)
-- [GitHub Repository](https://github.com/blueflyio/openstandardagents)
-- [Schema Download](https://openstandardagents.org/schemas/v0.2.x/agent.json)