TypeScript and Python Code Generators for OSSA Manifests

Code Generators for OSSA Manifests

Objective

Create code generators that transform OSSA agent manifests into type-safe client code, similar to OpenAPI Generator.

Supported Languages

TypeScript Generator

Generates TypeScript types and runtime helpers from OSSA manifests.

```typescript // Generated from agent.yaml export interface ComplianceScannerAgent { id: "compliance-scanner"; name: "Compliance Scanner"; version: "1.2.0"; capabilities: { scanResources: { input: ScanResourcesInput; output: ScanResourcesOutput; }; generateReport: { input: GenerateReportInput; output: GenerateReportOutput; }; }; }

// Runtime client const agent = new OSSAClient({ endpoint: "https://agents.example.com/compliance-scanner" });

const result = await agent.capabilities.scanResources({ resources: [...] }); ```

Python Generator

Generates Python dataclasses and Pydantic models.

```python

Generated from agent.yaml

from dataclasses import dataclass from typing import List

@dataclass class ComplianceScannerAgent: id: str = "compliance-scanner" name: str = "Compliance Scanner" version: str = "1.2.0"

class Capabilities:
    def scan_resources(self, input: ScanResourcesInput) -> ScanResourcesOutput:
        ...

Runtime usage

agent = OSSAClientComplianceScannerAgent

result = agent.capabilities.scan_resources(...) ```

Features

Core Generation

• Type definitions from JSON schemas
• Runtime client stubs
• Request/response validation
• Error handling utilities

Advanced Features

• Streaming support: For long-running capabilities
• Retry logic: Configurable retry strategies
• Observability: Auto-instrumentation with OpenTelemetry
• Mock generation: Test helpers and fixtures

CLI Interface

```bash

Generate TypeScript

ossa generate typescript agent.yaml --output ./generated/

Generate Python

ossa generate python agent.yaml --output ./generated/

Generate with custom templates

ossa generate ts agent.yaml --template ./custom-template/

Watch mode for development

ossa generate ts agent.yaml --watch ```

Implementation

Architecture

``` packages/generator/ ├── src/ │ ├── core/ │ │ ├── parser.ts # Parse OSSA manifest │ │ ├── transformer.ts # Transform to IR │ │ └── validator.ts # Validate before gen │ ├── generators/ │ │ ├── typescript/ │ │ │ ├── types.ts │ │ │ ├── client.ts │ │ │ └── templates/ │ │ └── python/ │ │ ├── models.ts │ │ ├── client.ts │ │ └── templates/ │ └── cli.ts ```

Template Engine

• Handlebars for flexibility
• Customizable templates
• Plugin system for extensions

Acceptance Criteria

• TypeScript generator produces valid, type-safe code
• Python generator produces Pydantic-compatible models
• Generated code compiles/runs without errors
• Generated clients handle all OSSA features (capabilities, protocols, etc.)
• Template customization supported
• Published to npm as `@ossa/generator`
• Comprehensive documentation with examples
• Integration tests with real agent manifests

Example Generated Output Quality

• Clean, readable code with comments
• Follows language idioms (PEP-8 for Python, prettier for TS)
• Includes JSDoc/docstrings from OSSA descriptions
• Tree-shakeable (dead code elimination)

Comparison to OpenAPI Generator

OSSA Generator should match OpenAPI Generator's polish:

• Multiple output formats
• Customizable templates
• Plugin architecture
• CI/CD friendly
• Well-documented

Labels

`tooling`, `code-generation`, `typescript`, `python`, `developer-experience`

Milestone

v0.3.0 - Reference Tooling