@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/spec/v0.2.2/ossa-reasoning-compliance-1.0.schema.json

@@ -0,0 +1,424 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/1.0/reasoning-compliance.json",
+  "title": "OSSA 1.0 Reasoning Compliance Extension",
+  "description": "OSSA extension for chain-of-thought reasoning compliance validation and auditing. Defines requirements for transparent, traceable, and auditable AI reasoning chains.",
+  "version": "1.0.0",
+  "type": "object",
+  "properties": {
+    "reasoningCompliance": {
+      "type": "object",
+      "description": "Reasoning compliance configuration and rules",
+      "required": ["enabled", "standard", "rules"],
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable reasoning compliance validation",
+          "default": true
+        },
+        "standard": {
+          "type": "string",
+          "enum": ["ossa_v1", "ossa_v2", "custom"],
+          "description": "Compliance standard to enforce",
+          "default": "ossa_v2"
+        },
+        "rules": {
+          "type": "array",
+          "description": "Compliance rules to enforce",
+          "items": {
+            "$ref": "#/definitions/ComplianceRule"
+          },
+          "minItems": 1
+        },
+        "attentionTracking": {
+          "type": "object",
+          "description": "Attention mechanism tracking requirements",
+          "properties": {
+            "required": {
+              "type": "boolean",
+              "description": "Whether attention tracking is required",
+              "default": true
+            },
+            "mechanisms": {
+              "type": "array",
+              "description": "Allowed attention mechanisms",
+              "items": {
+                "type": "string",
+                "enum": ["gqa", "flash_v3", "hybrid", "standard"]
+              },
+              "default": ["gqa", "flash_v3", "hybrid"]
+            },
+            "minimumHeads": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Minimum number of attention heads",
+              "default": 4
+            },
+            "trackingFrequency": {
+              "type": "string",
+              "enum": ["every_step", "decision_points", "critical_only"],
+              "description": "How frequently to track attention",
+              "default": "every_step"
+            }
+          }
+        },
+        "auditTrail": {
+          "type": "object",
+          "description": "Audit trail requirements",
+          "required": ["enabled"],
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Enable audit trail generation",
+              "default": true
+            },
+            "storageBackend": {
+              "type": "string",
+              "enum": ["neo4j", "postgres", "mongodb", "qdrant"],
+              "description": "Backend for audit trail storage"
+            },
+            "retentionDays": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "How long to retain audit trails",
+              "default": 90
+            },
+            "immutable": {
+              "type": "boolean",
+              "description": "Whether audit trails are immutable",
+              "default": true
+            },
+            "checksumAlgorithm": {
+              "type": "string",
+              "enum": ["sha256", "sha512", "blake2b"],
+              "description": "Checksum algorithm for audit trail integrity",
+              "default": "sha256"
+            }
+          }
+        },
+        "chainRequirements": {
+          "type": "object",
+          "description": "Requirements for reasoning chains",
+          "properties": {
+            "minimumSteps": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Minimum steps required in a reasoning chain",
+              "default": 3
+            },
+            "maximumSteps": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum allowed steps in a reasoning chain",
+              "default": 100
+            },
+            "requiredStepTypes": {
+              "type": "array",
+              "description": "Required step types that must be present",
+              "items": {
+                "type": "string",
+                "enum": ["observation", "hypothesis", "analysis", "decision", "action", "reflection"]
+              },
+              "default": ["observation", "analysis", "decision"]
+            },
+            "minimumConfidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Minimum average confidence threshold",
+              "default": 0.5
+            },
+            "requireDependencies": {
+              "type": "boolean",
+              "description": "Whether steps must declare dependencies",
+              "default": true
+            }
+          }
+        },
+        "transparencyRequirements": {
+          "type": "object",
+          "description": "Transparency and explainability requirements",
+          "properties": {
+            "requireExplanations": {
+              "type": "boolean",
+              "description": "Whether each step must include reasoning explanation",
+              "default": true
+            },
+            "minimumExplanationLength": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Minimum characters in reasoning explanation",
+              "default": 20
+            },
+            "exposeAttentionWeights": {
+              "type": "boolean",
+              "description": "Whether attention weights must be exposed",
+              "default": true
+            },
+            "requireVisualization": {
+              "type": "boolean",
+              "description": "Whether reasoning must be visualizable",
+              "default": false
+            }
+          }
+        },
+        "correlationRequirements": {
+          "type": "object",
+          "description": "Cross-chain correlation requirements",
+          "properties": {
+            "enableCrossChainTracking": {
+              "type": "boolean",
+              "description": "Enable tracking correlations across chains",
+              "default": true
+            },
+            "minimumCorrelationScore": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Minimum correlation score for flagging",
+              "default": 0.7
+            },
+            "detectAnomalies": {
+              "type": "boolean",
+              "description": "Enable attention anomaly detection",
+              "default": true
+            },
+            "anomalySeverityThreshold": {
+              "type": "string",
+              "enum": ["low", "medium", "high", "critical"],
+              "description": "Minimum severity to report anomalies",
+              "default": "medium"
+            }
+          }
+        },
+        "validationTriggers": {
+          "type": "array",
+          "description": "When to trigger compliance validation",
+          "items": {
+            "type": "string",
+            "enum": ["on_completion", "real_time", "scheduled", "on_demand"]
+          },
+          "default": ["on_completion"]
+        },
+        "enforcementLevel": {
+          "type": "string",
+          "enum": ["strict", "warn", "advisory"],
+          "description": "How to enforce compliance violations",
+          "default": "strict"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "ComplianceRule": {
+      "type": "object",
+      "required": ["ruleId", "name", "severity", "condition"],
+      "properties": {
+        "ruleId": {
+          "type": "string",
+          "pattern": "^[a-z0-9]([-_a-z0-9]*[a-z0-9])?$",
+          "description": "Unique rule identifier"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable rule name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Detailed rule description"
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["info", "warning", "error", "critical"],
+          "description": "Rule violation severity"
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "attention_quality",
+            "reasoning_clarity",
+            "step_completeness",
+            "dependency_integrity",
+            "confidence_threshold",
+            "transparency",
+            "auditability",
+            "correlation_integrity"
+          ],
+          "description": "Rule category"
+        },
+        "condition": {
+          "type": "object",
+          "description": "Rule condition specification",
+          "required": ["type"],
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": [
+                "min_steps",
+                "max_steps",
+                "required_types",
+                "min_confidence",
+                "max_low_confidence_ratio",
+                "attention_required",
+                "dependency_required",
+                "explanation_length",
+                "correlation_threshold",
+                "no_cycles",
+                "no_orphans"
+              ],
+              "description": "Condition type"
+            },
+            "value": {
+              "description": "Condition threshold value",
+              "oneOf": [
+                {"type": "number"},
+                {"type": "string"},
+                {"type": "boolean"},
+                {"type": "array"}
+              ]
+            },
+            "comparison": {
+              "type": "string",
+              "enum": ["eq", "ne", "gt", "gte", "lt", "lte", "in", "not_in", "contains"],
+              "description": "Comparison operator",
+              "default": "gte"
+            }
+          }
+        },
+        "remediation": {
+          "type": "string",
+          "description": "Suggested remediation for violation"
+        },
+        "autoFix": {
+          "type": "boolean",
+          "description": "Whether violation can be auto-fixed",
+          "default": false
+        },
+        "applicableToStepTypes": {
+          "type": "array",
+          "description": "Step types this rule applies to",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "array",
+          "description": "Rule tags for categorization",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "reasoningCompliance": {
+        "enabled": true,
+        "standard": "ossa_v2",
+        "rules": [
+          {
+            "ruleId": "min-steps-required",
+            "name": "Minimum Steps Required",
+            "description": "Reasoning chains must have at least 3 steps for adequate traceability",
+            "severity": "warning",
+            "category": "step_completeness",
+            "condition": {
+              "type": "min_steps",
+              "value": 3,
+              "comparison": "gte"
+            },
+            "remediation": "Add more reasoning steps to improve transparency and auditability"
+          },
+          {
+            "ruleId": "attention-weights-required",
+            "name": "Attention Weights Required",
+            "description": "All reasoning steps must include attention weight tracking",
+            "severity": "critical",
+            "category": "attention_quality",
+            "condition": {
+              "type": "attention_required",
+              "value": true,
+              "comparison": "eq"
+            },
+            "remediation": "Add attention mechanism to all reasoning steps"
+          },
+          {
+            "ruleId": "min-confidence-threshold",
+            "name": "Minimum Confidence Threshold",
+            "description": "Reasoning steps must maintain minimum confidence level",
+            "severity": "error",
+            "category": "confidence_threshold",
+            "condition": {
+              "type": "min_confidence",
+              "value": 0.5,
+              "comparison": "gte"
+            },
+            "remediation": "Review and improve reasoning quality to meet confidence threshold"
+          },
+          {
+            "ruleId": "dependency-declaration",
+            "name": "Dependency Declaration Required",
+            "description": "Non-initial steps must declare dependencies on previous steps",
+            "severity": "warning",
+            "category": "dependency_integrity",
+            "condition": {
+              "type": "dependency_required",
+              "value": true,
+              "comparison": "eq"
+            },
+            "remediation": "Add explicit dependencies to maintain reasoning chain integrity"
+          },
+          {
+            "ruleId": "explanation-min-length",
+            "name": "Explanation Minimum Length",
+            "description": "Reasoning explanations must be sufficiently detailed",
+            "severity": "warning",
+            "category": "transparency",
+            "condition": {
+              "type": "explanation_length",
+              "value": 20,
+              "comparison": "gte"
+            },
+            "remediation": "Provide more detailed reasoning explanations"
+          }
+        ],
+        "attentionTracking": {
+          "required": true,
+          "mechanisms": ["gqa", "flash_v3", "hybrid"],
+          "minimumHeads": 4,
+          "trackingFrequency": "every_step"
+        },
+        "auditTrail": {
+          "enabled": true,
+          "storageBackend": "neo4j",
+          "retentionDays": 90,
+          "immutable": true,
+          "checksumAlgorithm": "sha256"
+        },
+        "chainRequirements": {
+          "minimumSteps": 3,
+          "maximumSteps": 50,
+          "requiredStepTypes": ["observation", "analysis", "decision"],
+          "minimumConfidence": 0.5,
+          "requireDependencies": true
+        },
+        "transparencyRequirements": {
+          "requireExplanations": true,
+          "minimumExplanationLength": 20,
+          "exposeAttentionWeights": true,
+          "requireVisualization": false
+        },
+        "correlationRequirements": {
+          "enableCrossChainTracking": true,
+          "minimumCorrelationScore": 0.7,
+          "detectAnomalies": true,
+          "anomalySeverityThreshold": "medium"
+        },
+        "validationTriggers": ["on_completion", "real_time"],
+        "enforcementLevel": "strict"
+      }
+    }
+  ]
+}
+

package/spec/v0.2.3/CHANGELOG.md

@@ -0,0 +1,176 @@
+# OSSA v0.2.3 Release Notes
+
+**Release Date**: 2025-11-12
+**Type**: Patch Release (Documentation & Examples)
+**Status**: Production Ready
+
+## Overview
+
+OSSA v0.2.3 is a documentation-focused patch release that enhances examples, improves migration guides, and prepares the package for npm publication. The schema remains unchanged from v0.2.2, ensuring full backward compatibility.
+
+## What's New
+
+### Documentation Improvements
+
+#### ✅ Enhanced Examples
+- Added comprehensive inline documentation to 10 priority examples
+- Annotated kAgent examples with best practices
+- Improved getting-started guides with step-by-step instructions
+- Added production-ready enterprise agent examples
+
+#### ✅ Migration Guides (6 Frameworks)
+- **LangChain → OSSA**: Complete migration workflow with code examples
+- **CrewAI → OSSA**: Multi-agent orchestration patterns
+- **OpenAI Agents SDK → OSSA**: Assistants API conversion
+- **Anthropic MCP → OSSA**: Model Context Protocol bridge
+- **Langflow → OSSA**: Visual flow-to-manifest conversion
+- **Drupal ECA → OSSA**: Event-Condition-Action migration
+
+#### ✅ GitLab Wiki Integration
+- Migrated documentation to GitLab wiki
+- Added issue templates for standardized reporting
+- Created milestone tracking system
+- Integrated CI/CD documentation
+
+#### ✅ OpenAPI Extensions Documentation
+- Documented x-ossa-agent extension
+- Added x-ossa-manifest reference guide
+- Explained framework-specific extensions
+- Provided OpenAPI spec generation examples
+
+### Examples & Templates
+
+#### New Examples
+- `examples/kagent/README.md` - kAgent integration guide
+- `examples/integration-patterns/agent-to-agent-orchestration.ossa.yaml`
+- `examples/production/enterprise-agent.ossa.yaml`
+
+#### Updated Examples
+All kagent examples updated with:
+- Detailed inline comments
+- Best practice annotations
+- Real-world use cases
+- Troubleshooting tips
+
+### Build & Infrastructure
+
+#### ✅ npm Publishing Preparation
+- Package configured for public npm registry
+- Build artifacts optimized
+- Dependencies audited and updated
+- prepublishOnly hooks configured
+
+#### ✅ CI/CD Improvements
+- Consolidated GitLab CI/CD pipeline
+- Added comprehensive test coverage reports
+- Implemented security audit checks
+- Configured manual release triggers
+
+## Breaking Changes
+
+**None** - This release is fully backward compatible with v0.2.2.
+
+## Deprecations
+
+**None**
+
+## Bug Fixes
+
+- Fixed schema validation for edge cases
+- Corrected example formatting inconsistencies
+- Updated broken documentation links
+- Resolved CI pipeline configuration issues
+
+## Schema Changes
+
+**No schema changes** - v0.2.3 schema is identical to v0.2.2 with updated version metadata only.
+
+## Migration from v0.2.2
+
+### Required Changes
+**None** - Simply update your `apiVersion` field (optional):
+
+```yaml
+# Both versions work identically
+apiVersion: ossa/v0.2.2  # Still valid
+apiVersion: ossa/v0.2.4  # Recommended
+```
+
+### Recommended Changes
+1. Review new migration guides if integrating with frameworks
+2. Update documentation references to use v0.2.3
+3. Check out new examples for best practices
+
+See [migrations/v0.2.2-to-v0.2.3.md](migrations/v0.2.2-to-v0.2.3.md) for detailed migration guide.
+
+## Installation
+
+### npm (Recommended)
+```bash
+npm install -g @bluefly/openstandardagents@0.2.3
+```
+
+### GitLab Package Registry
+```bash
+npm install @bluefly/openstandardagents@0.2.3
+```
+
+### Verify Installation
+```bash
+ossa --version
+# Output: 0.2.3
+```
+
+## Compatibility
+
+| Component | Version | Status |
+|-----------|---------|--------|
+| Node.js | >=18.0.0 | ✅ Required |
+| npm | >=9.0.0 | ✅ Required |
+| kAgent | v1alpha1 | ✅ Full support |
+| Drupal | 11.x, 10.x | ✅ Full support |
+| OpenAI SDK | v2.x | ✅ Full support |
+| LangChain | v0.3.x | ✅ Full support |
+| CrewAI | v0.11.x | ✅ Full support |
+| MCP | Latest | ✅ Full support |
+
+## Known Issues
+
+**None** - All tests passing (67/67)
+
+## Security
+
+- ⚠️ **4 moderate vulnerabilities** in semantic-release dependency chain
+  - Impact: Dev dependencies only (not production runtime)
+  - Status: Monitoring upstream for fixes
+  - Workaround: Not required for normal usage
+
+## Contributors
+
+- Full git cleanup and version standardization
+- Documentation migration to GitLab wiki
+- CI/CD pipeline consolidation
+- npm publishing preparation
+
+## Next Steps (v0.3.0 Planned)
+
+### Gamma Release Roadmap
+- [ ] Enhanced validation rules
+- [ ] Additional framework extensions
+- [ ] Performance optimizations
+- [ ] Extended examples library
+- [ ] Agent marketplace integration
+
+## Support
+
+- **Documentation**: https://github.com/blueflyio/openstandardagents
+- **Issues**: https://github.com/blueflyio/openstandardagents/issues
+- **Examples**: https://github.com/blueflyio/openstandardagents/tree/main/examples
+
+## Acknowledgments
+
+Special thanks to the OSSA community for feedback and contributions!
+
+---
+
+**Full Changelog**: [v0.2.2...v0.2.3](https://github.com/blueflyio/openstandardagents/compare/v0.2.2...v0.2.3)