Metadata-Version: 2.4
Name: holosdk-cli
Version: 0.3.0
Summary: OpenAPI SDK generator with fuzzy endpoint matching, MCP server output, and AI-powered spec analysis
Author-email: Strategic Innovations AI <noreply@strategic-innovations.ai>
License: Patent Pending — Strategic Innovations AI
Keywords: sdk,openapi,codegen,mcp,cli,api,fuzzy-matching
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"

# HoloSDK

> Generate SDKs, MCP servers, and CLIs from OpenAPI specs — with fuzzy endpoint matching.

HoloSDK is an OpenAPI SDK generator that encodes API endpoints into a
compact vector index. This enables fuzzy endpoint matching at runtime —
your SDK handles typos, path variations, and version drift without
breaking.

## Quick Start

```bash
pip install holosdk-cli
```

```bash
# Generate a TypeScript SDK
holosdk generate --spec openapi.json --lang typescript --out ./sdk

# Generate a Python SDK
holosdk generate --spec openapi.json --lang python --out ./sdk

# Generate a Go SDK
holosdk generate --spec openapi.json --lang go --out ./sdk

# Generate an MCP server (JSON-RPC over stdio)
holosdk generate --spec openapi.json --lang mcp --out ./server --base-url https://api.example.com

# Generate a CLI tool
holosdk generate --spec openapi.json --lang cli --out ./cli.py --base-url https://api.example.com

# Compose multiple APIs into one SDK
holosdk compose --specs stripe.json github.json --lang typescript --out ./sdk

# Diff two spec versions and generate a migration guide
holosdk diff --old v1.json --new v2.json --out migration-guide.md

# Inspect a spec
holosdk inspect --spec openapi.json
```

## Features

- **5 output targets**: TypeScript, Python, Go, MCP Server, CLI
- **Fuzzy endpoint matching**: bigram Jaccard similarity handles typos
  and path variations at runtime — no more 404s from a missing slash
- **Multi-API composition**: combine multiple OpenAPI specs into a
  single SDK with automatic namespace conflict detection
- **Spec diff & migration**: compare old vs new spec versions, generate
  human-readable migration guides with breaking change detection
- **Embedded endpoint index**: generated SDKs contain endpoint metadata
  for runtime resolution — no external lookup needed
- **Zero runtime dependencies**: generated SDKs are self-contained (no
  pip/npm installs required to use them)

## Architecture

```
OpenAPI Spec
    |
    v
SpecParser --> EndpointEncoder --> EndpointIndex (D=10000)
    |                                |
    |                    +-----------+-----------+
    |                    |           |           |
    v                    v           v           v
TSCodeGenerator   PyCodeGenerator  GoCodeGenerator  MCPGenerator
```

Each endpoint is encoded as a D-dimensional complex unit-circle
vector via phase addition of method + path encodings. Endpoints
are accumulated into a single composite index. At runtime, queries
are encoded the same way and matched via similarity scoring against
the composite.

## CLI Commands

| Command | Description |
|---------|-------------|
| `generate` | Generate SDK from a single OpenAPI spec |
| `compose` | Compose multiple APIs into one SDK |
| `inspect` | Inspect spec stats and endpoint index info |
| `diff` | Diff two spec versions, generate migration guide |

## Output Languages

### TypeScript (--lang typescript)
Full SDK with types, methods, HTTP client class, embedded endpoint
index, and resolveEndpoint() for fuzzy matching.

### Python (--lang python)
Dataclass-based SDK with type hints, async-ready methods, embedded
endpoint index, and resolve_endpoint() for fuzzy matching.

### Go (--lang go)
Idiomatic Go with structs, pointer-optional params, error returns,
and ResolveEndpoint() for fuzzy matching.

### MCP Server (--lang mcp)
Standalone JSON-RPC 2.0 server over stdio. Each endpoint becomes an
MCP tool with proper inputSchema. Handles initialize, tools/list,
and tools/call with path param substitution and HTTP requests.

### CLI (--lang cli)
Standalone argparse-based CLI tool. Each endpoint becomes a subcommand
(kebab-cased). Path params become positional args, query/body params
become --flags. Embeds fuzzy command matching for typo tolerance.
Proxies to the actual API via urllib.

## Cloud Service

HoloSDK Cloud provides AI-powered features on top of the CLI:

- **MCP description generation** — auto-write tool descriptions from specs
- **Spec analysis** — detect breaking changes, suggest improvements
- **Migration guides** — AI-generated upgrade paths between API versions
- **Semantic diff** — understand what changed between spec versions
- **Test generation** — generate test suites from OpenAPI specs

Cloud API: https://holosdk.strategic-innovations.ai

## Installation

```bash
pip install holosdk-cli          # CLI + Python SDK
pip install holosdk-cli[yaml]    # with YAML spec support
pip install holosdk-cli[dev]     # with pytest + YAML for development
```

Requires Python 3.9+. Only dependency: numpy.

## Project Stats

- 16 modules, 14 test files
- 102 tests, all passing
- ~3700 LOC
- Zero external dependencies beyond numpy
- Python 3.9+

## License

Proprietary. All rights reserved.
