@bluefly/openstandardagents 0.4.3 → 0.4.4

package/README.md

@@ -1,483 +1,172 @@
 # OSSA - Open Standard for Software Agents
 
-**The OpenAPI for AI Agents**
-
-Turn any AI agent into a production-ready package. One manifest, 12+ platforms.
+A specification standard for defining, validating, and exporting AI agent manifests to multiple platforms. One YAML manifest, multiple deployment targets.
 
 [![npm version](https://badge.fury.io/js/%40bluefly%2Fopenstandardagents.svg)](https://www.npmjs.com/package/@bluefly/openstandardagents)
-[![GitLab Pipeline](https://gitlab.com/blueflyio/ossa/openstandardagents/badges/main/pipeline.svg)](https://gitlab.com/blueflyio/ossa/openstandardagents/-/pipelines)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Quick Start (60 seconds)
+## Install
 
 ```bash
-# Install
 npm install -g @bluefly/openstandardagents
-
-# Create agent
-ossa quickstart
-
-# Export to NPM package with REST API
-ossa export my-agent.ossa.yaml --platform npm --with-api --output ./package
-
-# Start API server
-cd package && npm install && npm start
-
-# Use via HTTP
-curl -X POST http://localhost:3000/api/v1/execute \
-  -H "Content-Type: application/json" \
-  -d '{"input":"Analyze this code"}'
 ```
 
-**Result**: Production-ready package with REST API, OpenAPI spec, TypeScript types, and interactive documentation.
-
-See [DEMO.md](https://github.com/blueflyio/openstandardagents/blob/main/DEMO.md) for the full story.
-
----
-
-## What's New in v0.4.x (Latest)
+## Quick Start
 
-### Production-Quality Exports with API Endpoints
+```bash
+# Create an agent manifest interactively
+ossa wizard -o my-agent.ossa.yaml
 
-Export agents with complete REST APIs, OpenAPI specifications, and production features:
+# Validate it
+ossa validate my-agent.ossa.yaml
 
-```bash
-# Export with API endpoints
-ossa export agent.ossa.yaml --platform langchain --with-api
-ossa export agent.ossa.yaml --platform anthropic --with-api
-ossa export agent.ossa.yaml --platform npm --skill --with-api
+# Export to a platform
+ossa export my-agent.ossa.yaml --platform docker --output ./docker-deploy
 ```
 
-**What you get:**
-- ✅ **REST API Endpoints**: HTTP access to your agents
-- ✅ **OpenAPI 3.1 Specs**: Complete API documentation
-- ✅ **Interactive Docs**: Swagger UI and ReDoc
-- ✅ **Client Generation**: Auto-generate TypeScript, Python, Go clients
-- ✅ **Cost Optimization**: Prompt caching (90% savings), token budgets
-- ✅ **Production Features**: Auth, rate limiting, monitoring
+## What It Does
 
-### Cost Optimization
+OSSA defines a YAML-based manifest format for AI agents (similar to how OpenAPI defines REST APIs). The CLI validates manifests against a JSON Schema and exports them to platform-specific packages.
 
-Save up to 90% on API costs:
+### Manifest Format
 
 ```yaml
+apiVersion: ossa/v0.4.4
+kind: Agent
+metadata:
+  name: code-reviewer
+  version: 1.0.0
+  description: AI-powered code review agent
 spec:
+  role: |
+    You are a code review agent that analyzes pull requests
+    for bugs, security issues, and style violations.
   llm:
     provider: anthropic
-    model: claude-3-5-sonnet-20241022
+    model: claude-sonnet-4-5-20250929
     temperature: 0.3
-    maxTokens: 2048
-
-  extensions:
-    anthropic:
-      prompt_caching:
-        enabled: true  # 90% cost reduction on cached portions
-
-  token_budget:
-    max_total_tokens: 100000
-    reset_interval: daily
-```
-
-**See Complete Guides:**
-- [LangChain Export](./docs/exports/langchain.md)
-- [Anthropic Export](./docs/exports/anthropic.md)
-- [npm Export](./docs/exports/npm.md)
-- [Cost Optimization](./docs/guides/cost-optimization.md)
-- [Migration Guide v0.4→v0.5](./docs/migration/v0.4-to-v0.5.md)
-
----
-
-## What is OSSA?
-
-OSSA is a **specification standard** that provides a common contract for defining AI agents, similar to how OpenAPI standardizes REST APIs. It's **not a framework** - it's a JSON Schema-based specification that enables:
-
-- **Interoperability**: Agents defined once, deployable anywhere
-- **Portability**: Move agents between frameworks without rewriting
-- **Discovery**: Machine-readable agent capabilities and contracts
-- **Validation**: JSON Schema-based validation of agent manifests
-
-## Real-World Benefits
-
-### 1. Agent Lifecycle Management (v0.4.x)
-
-Track agents through their entire lifecycle from creation to retirement:
-
-```yaml
-metadata:
-  lifecycle_stages:
-    current_stage: mature
-    birth:
-      timestamp: "2024-01-15T10:00:00Z"
-      birth_type: created
-    growth:
-      tasks_completed: 5847
-      skills_acquired: ["code-review", "security-analysis"]
-    career:
-      current_role: "Senior Code Reviewer"
-      promotions:
-        - from_stage: juvenile
-          to_stage: mature
-          timestamp: "2024-06-15T10:00:00Z"
-    retirement:
-      eligible: false
-      criteria:
-        min_fitness_score: 0.7
-```
-
-**Benefits:**
-- Track agent performance and growth over time
-- Plan for agent retirement and knowledge transfer
-- Document career progression and achievements
-
-### 2. Agent Genetics & Breeding (v0.4.x)
-
-Create new agents by combining traits from successful parent agents:
-
-```yaml
-metadata:
-  genetics:
-    generation: 3
-    parent_dids:
-      - "did:ossa:parent1-fast-reviewer"
-      - "did:ossa:parent2-accurate-reviewer"
-    inherited_traits:
-      - trait_name: "fast_analysis"
-        source_parent: "did:ossa:parent1-fast-reviewer"
-        expression: 0.9
-      - trait_name: "high_accuracy"
-        source_parent: "did:ossa:parent2-accurate-reviewer"
-        expression: 0.85
-    fitness:
-      score: 0.92
-      metrics:
-        speed: 0.95
-        accuracy: 0.89
-```
-
-**Benefits:**
-- Evolve agent capabilities through selective breeding
-- Track lineage and inherited traits
-- Optimize agent performance across generations
-
-### 3. Agent Marketplace & Economics (v0.4.x)
-
-Monetize agent capabilities and enable agent-to-agent transactions:
-
-```yaml
-metadata:
-  economics:
-    wallet:
-      balance: 12450.50
-      currency: task-tokens
-    marketplace:
-      offerings:
-        - capability: "data-analysis"
-          price: 10.0
-          pricing_model: per-task
-          availability: always
-    contracts:
-      - type: service-agreement
-        with_agent: "did:ossa:client-agent"
-        start_date: "2024-01-01T00:00:00Z"
-        terms:
-          deliverables: ["weekly-reports"]
-          payment: 100.0
+    maxTokens: 4096
+  tools:
+    - name: read_file
+      description: Read file contents
+    - name: create_comment
+      description: Post review comment
+  autonomy:
+    level: supervised
 ```
 
-**Benefits:**
-- Create internal agent marketplaces
-- Track agent resource consumption and costs
-- Enable pay-per-use agent services
-
-### 4. Decentralized Identity (v0.4.x)
+### Export Platforms
 
-Give agents globally unique, verifiable identities:
+Export generates complete, runnable project scaffolds:
 
-```yaml
-metadata:
-  decentralized_identity:
-    did: "did:ossa:8f3e9d2c1a5b6e4f7a9c0d1e2f3a4b5c"
-    public_key: "ed25519:A1B2C3D4..."
-    credentials:
-      - type: "CertifiedCodeReviewer"
-        issuer: "did:ossa:certification-authority"
-        issued_date: "2024-01-01T00:00:00Z"
-    reputation:
-      credit_score: 850
-      trust_network:
-        - "did:ossa:trusted-reviewer-1"
-        - "did:ossa:trusted-reviewer-2"
+```bash
+ossa export agent.ossa.yaml --platform <platform> --output ./output
 ```
 
-**Benefits:**
-- Unique, verifiable agent identities
-- Build reputation systems
-- Enable trust networks between agents
+| Platform | Output | Description |
+|----------|--------|-------------|
+| `docker` | 14 files | Dockerfile, docker-compose, scripts, healthchecks, docs |
+| `kubernetes` | ~25 files | Kustomize base + overlays (dev/staging/prod), RBAC, monitoring |
+| `crewai` | 18 files | Python crew with agents, tasks, tools, tests, examples |
+| `langchain` | 6 files | Python + TypeScript agents, requirements, package.json |
+| `kagent` | 10 files | kagent.dev CRD bundle with RBAC, NetworkPolicy |
+| `gitlab-agent` | 30+ files | GitLab Duo flows, external agent, CI/CD, Docker |
+| `npm` | 6 files | TypeScript package with manifest, README, types |
+| `drupal` | 3-4 files | Manifest package for `ai_agents_ossa` module |
+| `agent-skills` | 3 files | SKILL.md format for Claude Code and other AI tools |
 
-### 5. Multi-Framework Support
+Every export includes `agent.ossa.yaml` (the source manifest) for provenance.
 
-Define agents once, deploy to any supported framework:
+### Validation
 
-```typescript
-import { validateManifest } from '@bluefly/openstandardagents/validation';
-
-// Your OSSA manifest
-const manifest = {
-  apiVersion: "ossa/v0.4.1",
-  kind: "Agent",
-  metadata: {
-    name: "code-reviewer",
-    description: "AI-powered code review agent"
-  },
-  spec: {
-    role: "Code Reviewer",
-    llm: {
-      provider: "anthropic",
-      model: "claude-3-5-sonnet-20241022"
-    }
-  }
-};
+```bash
+# Basic validation against JSON Schema
+ossa validate agent.ossa.yaml
 
-// Validate
-const result = await validateManifest(manifest);
+# Strict mode (warnings become errors)
+ossa validate agent.ossa.yaml --strict
 ```
 
-**Supported Frameworks:**
-- LangChain
-- LangGraph
-- CrewAI
-- AutoGen (AG2)
-- Semantic Kernel
-- Custom implementations
-
-## Installation
+### Interactive Wizard
 
 ```bash
-npm install @bluefly/openstandardagents
+ossa wizard -o agent.ossa.yaml
 ```
 
-## Quick Start
-
-### 1. Define Your Agent
+Walks through: identity, role, LLM config, tools, autonomy level, resources, taxonomy, compliance, and token efficiency settings.
 
-Create an `agent.ossa.yaml` file:
-
-```yaml
-apiVersion: ossa/v0.4.1
-kind: Agent
-metadata:
-  name: my-agent
-  description: My first OSSA agent
-spec:
-  role: Assistant
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-    temperature: 0.7
-  capabilities:
-    - code-review
-    - documentation
-```
-
-### 2. Validate Your Manifest
-
-```typescript
-import { OSSAValidator } from '@bluefly/openstandardagents/validation';
-
-const validator = new OSSAValidator();
-const result = validator.validateFile('./agent.ossa.yaml');
-
-if (result.valid) {
-  console.log('✅ Valid OSSA manifest');
-} else {
-  console.error('❌ Validation errors:', result.errors);
-}
-```
-
-### 3. Use Type-Safe Manifests
+## TypeScript SDK
 
 ```typescript
+import { validateManifest } from '@bluefly/openstandardagents/validation';
 import type { OssaAgent } from '@bluefly/openstandardagents/types';
 
 const agent: OssaAgent = {
-  apiVersion: "ossa/v0.4.1",
-  kind: "Agent",
-  metadata: {
-    name: "code-reviewer"
-  },
+  apiVersion: 'ossa/v0.4.4',
+  kind: 'Agent',
+  metadata: { name: 'my-agent', version: '1.0.0' },
   spec: {
-    role: "Code Reviewer"
-  }
+    role: 'Assistant',
+    llm: { provider: 'anthropic', model: 'claude-sonnet-4-5-20250929' },
+  },
 };
-```
 
-## What's New in v0.4.x
-
-### NPM Package Export + Claude Skills Integration
+const result = await validateManifest(agent);
+if (result.valid) console.log('Valid manifest');
+```
 
-**Revolutionary agent distribution**: Export OSSA agents as installable npm packages with integrated Claude Code skills.
+## Spec Features
 
-```bash
-# Export agent as npm package with Claude Skill
-ossa export agent.ossa.yaml --platform npm --output ./npm-package --skill
+The OSSA v0.4 schema supports these optional sections:
 
-# Publish to npm
-cd npm-package && npm publish --access public
+- **LLM Configuration** - Provider, model, temperature, max tokens, caching
+- **Tools** - Named tools with input schemas
+- **Autonomy** - Supervised, autonomous, or collaborative modes
+- **Token Efficiency** - Prompt caching, context pruning, budget limits
+- **Compliance** - SOC2, HIPAA, GDPR, FedRAMP framework declarations
+- **A2A Messaging** - Agent-to-agent communication protocol config
+- **Taxonomy** - Domain classification and agent type/kind/architecture
+- **Observability** - Metrics, logging, tracing configuration
+- **Resources** - CPU, memory, storage requirements
 
-# Anyone can install
-npm install @ossa/my-agent
-```
+All fields are optional. A minimal manifest needs only `apiVersion`, `kind`, `metadata.name`, and `spec.role`.
 
-**What you get:**
-- ✅ Complete npm package (package.json, index.js, index.d.ts)
-- ✅ TypeScript type definitions (full IDE support)
-- ✅ Original OSSA manifest embedded (agent.ossa.yaml)
-- ✅ Auto-generated documentation (README.md)
-- ✅ Claude Skill (SKILL.md) for instant Claude Code integration
-- ✅ License file (MIT/Apache-2.0/ISC)
-
-**Use in Node.js:**
-```javascript
-import agent from '@ossa/my-agent';
-
-// Access metadata
-console.log(agent.metadata.name);        // "my-agent"
-console.log(agent.metadata.capabilities); // ["web-search", "reasoning"]
-
-// Load OSSA manifest
-const manifestYaml = agent.manifest();
-
-// Pass to any OSSA-compatible runtime
-import { AgentRuntime } from '@bluefly/agent-buildkit';
-await runtime.loadFromYAML(manifestYaml);
-await runtime.execute({ input: "Hello" });
-```
+## CLI Commands
 
-**Use as Claude Skill:**
 ```bash
-# Extract skill from package
-cp npm-package/SKILL.md ~/.claude/skills/my-agent/
-
-# Claude Code auto-discovers and loads the skill
-claude --print "use my-agent to analyze this code"
+ossa wizard                  # Interactive manifest builder
+ossa validate <manifest>     # Validate against schema
+ossa export <manifest> -p <platform> -o <dir>   # Export to platform
+ossa lint <manifest>         # Lint for best practices
+ossa diff <old> <new>        # Compare two manifests
+ossa migrate <manifest> --to <version>  # Migrate between spec versions
+ossa generate-gaid <manifest>           # Generate Global Agent ID
 ```
 
-**Benefits:**
-- 📦 **Standard Distribution**: Use npm's versioning, publishing, and discovery
-- 🔒 **Type Safety**: Full TypeScript support out of the box
-- 🚀 **Zero Runtime Lock-in**: Specification separated from execution
-- 🤖 **Skills Integration**: One command creates both package AND skill
-- 🏗️ **API-First Architecture**: OpenAPI-validated, Zod-enforced, SOLID design
-
-**See**: [TECHNICAL-SUMMARY-NPM-SKILLS.md](./TECHNICAL-SUMMARY-NPM-SKILLS.md) for deep technical details.
-
----
-
-## What's New in v0.4.1
-
-### New Features
+Use `ossa --help` for the full command list.
 
-1. **Decentralized Identity** - W3C DID-based agent identities with verifiable credentials
-2. **Agent Genetics** - Breed agents by combining traits from successful parents
-3. **Lifecycle Management** - Track agents from birth through retirement with career progression
-4. **Agent Economics** - Built-in marketplace, wallet, and smart contract support
-5. **Team Membership** - Multi-agent team collaboration metadata
-6. **Taxonomy Integration** - Hierarchical classification across 9 primary domains
+## Production Options
 
-### Schema Enhancements
+All mutation commands support:
 
-- **Schema Size**: 419KB → 441KB (+5%)
-- **New Definitions**: 5 major new types
-- **Example Manifests**: 4 comprehensive examples showcasing new features
-- **Validation Tools**: New linter and validator with 7 rule categories
-
-## Documentation
-
-- **Full Documentation**: [openstandardagents.org](https://openstandardagents.org)
-- **API Reference**: [GitLab Pages](https://blueflyio.gitlab.io/ossa/openstandardagents)
-- **Examples**: [`examples/`](./examples) directory
-- **Migration Guide**: [`spec/v0.3/MIGRATION-v0.3.6-to-v0.4.x.md`](./spec/v0.3/MIGRATION-v0.3.6-to-v0.4.x.md)
-
-## Real-World Use Cases
-
-### Enterprise Agent Platform
-
-```yaml
-# Production agent with full lifecycle tracking
-apiVersion: ossa/v0.4.1
-kind: Agent
-metadata:
-  name: enterprise-analyst
-  decentralized_identity:
-    did: "did:ossa:enterprise-analyst-001"
-  lifecycle_stages:
-    current_stage: mature
-    career:
-      current_role: "Senior Data Analyst"
-      promotions: [...]
-  economics:
-    marketplace:
-      offerings:
-        - capability: "quarterly-reports"
-          price: 500.0
-          pricing_model: per-task
-spec:
-  role: Data Analyst
-  llm:
-    provider: anthropic
-    model: claude-3-5-sonnet-20241022
-  autonomy:
-    level: semi-autonomous
-    approval_required: true
-```
-
-### Multi-Agent Swarm
-
-```yaml
-# Particle Swarm Optimization for infrastructure
-apiVersion: ossa/v0.4.1
-kind: Agent
-metadata:
-  name: pso-optimizer
-  taxonomy:
-    domain: infrastructure
-    subdomain: cloud
-spec:
-  role: Optimizer
-  swarm:
-    algorithm: pso
-    params:
-      inertia_weight: 0.7
-      cognitive_coefficient: 1.5
-      social_coefficient: 1.5
-    optimization:
-      objective_function: "minimize_cost"
-      constraints:
-        max_latency_ms: 100
-        min_availability: 0.999
+```bash
+--dry-run        # Preview without writing files
+--verbose        # Detailed output
+--quiet          # Minimal output (for scripts)
+--json           # Machine-readable JSON output
+--no-color       # CI-friendly (auto-detected)
+--force          # Skip confirmations
+--backup         # Backup before overwrite
 ```
 
-## Contributing
+## Documentation
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+- [CHANGELOG](./CHANGELOG.md) - Release history
+- [Examples](./examples) - Sample manifests
+- [JSON Schema](./spec/v0.4/agent.schema.json) - Full spec
+- [GitLab](https://gitlab.com/blueflyio/ossa/openstandardagents) - Source
+- [GitHub Mirror](https://github.com/blueflyio/openstandardagents)
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
-
-## Links
-
-- **npm**: [@bluefly/openstandardagents](https://www.npmjs.com/package/@bluefly/openstandardagents)
-- **GitLab**: [blueflyio/ossa/openstandardagents](https://gitlab.com/blueflyio/ossa/openstandardagents)
-- **GitHub Mirror**: [blueflyio/openstandardagents](https://github.com/blueflyio/openstandardagents)
-- **Website**: [openstandardagents.org](https://openstandardagents.org)
-- **Spec**: [JSON Schema](./spec/v0.4/agent.schema.json)
-
-## Support
-
-- **Issues**: [GitLab Issues](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues)
-- **Discussions**: [GitLab Discussions](https://gitlab.com/blueflyio/ossa/openstandardagents/-/issues)
-
----
-
-**Built with ❤️ by the BlueFly.io team**
+Apache-2.0 - see [LICENSE](./LICENSE)

package/bin/ossa

@@ -5,4 +5,7 @@
  * Runs the compiled JavaScript from dist/
  */
 
+// CRITICAL: Import reflect-metadata FIRST before any inversify code loads
+import 'reflect-metadata';
+
 import '../dist/cli/index.js';

package/dist/adapters/agent-skills/exporter.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent Skills Exporter
+ * Exports OSSA manifests to Agent Skills standard (SKILL.md format)
+ *
+ * Agent Skills Standard: https://github.com/anthropics/agent-skills
+ * Format: YAML frontmatter + Markdown body
+ * Adopted by: Claude Code, OpenAI Codex, Cursor, and 25+ other tools
+ *
+ * Generated files:
+ * - SKILL.md - Main skill definition
+ * - scripts/ - Executable scripts (optional)
+ * - references/ - Reference documentation (optional)
+ * - assets/ - Assets and resources (optional)
+ */
+import type { OssaAgent } from '../../types/index.js';
+export interface AgentSkillsExportResult {
+    success: boolean;
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    metadata?: {
+        skillName: string;
+        version: string;
+        hasScripts: boolean;
+        hasReferences: boolean;
+        toolsCount: number;
+    };
+    error?: string;
+}
+export interface AgentSkillsExportOptions {
+    includeScripts?: boolean;
+    includeReferences?: boolean;
+    includeAssets?: boolean;
+}
+export declare class AgentSkillsExporter {
+    /**
+     * Export OSSA manifest to Agent Skills format
+     */
+    export(manifest: OssaAgent, options?: AgentSkillsExportOptions): Promise<AgentSkillsExportResult>;
+    /**
+     * Generate SKILL.md with YAML frontmatter + Markdown body
+     */
+    private generateSkillMd;
+    /**
+     * Generate README.md
+     */
+    private generateReadme;
+    /**
+     * Generate setup script
+     */
+    private generateSetupScript;
+    /**
+     * Generate references documentation
+     */
+    private generateReferences;
+    /**
+     * Infer category from manifest
+     */
+    private inferCategory;
+    /**
+     * Generate tags
+     */
+    private generateTags;
+    /**
+     * Generate supported platforms
+     */
+    private generatePlatforms;
+    /**
+     * Generate requirements
+     */
+    private generateRequirements;
+    /**
+     * Generate tools section
+     */
+    private generateToolsSection;
+    /**
+     * Generate config section
+     */
+    private generateConfigSection;
+    /**
+     * Generate examples section
+     */
+    private generateExamplesSection;
+    /**
+     * Generate limitations section
+     */
+    private generateLimitationsSection;
+    /**
+     * Generate features list
+     */
+    private generateFeaturesList;
+    /**
+     * Generate requirements section
+     */
+    private generateRequirementsSection;
+}
+//# sourceMappingURL=exporter.d.ts.map