Metadata-Version: 2.4
Name: holosdk-cli
Version: 0.3.1
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: Proprietary — Strategic Innovations AI. All rights reserved.
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
License-File: LICENSE
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"
Dynamic: license-file

# 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
    |                                |
    |                    +-----------+-----------+
    |                    |           |           |
    v                    v           v           v
TSCodeGenerator   PyCodeGenerator  GoCodeGenerator  MCPGenerator
```

The parser reads your spec, the encoder builds an index of its
endpoints, and each generator emits a client from that index. The
index is embedded in the generated SDK, so resolution happens locally
with no callback to HoloSDK and no lookup table to keep in sync.
Resolution cost stays flat as an API grows.

## 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.
