{"id":35699002,"url":"https://github.com/hiddenpath/ai-protocol","last_synced_at":"2026-03-08T08:05:11.092Z","repository":{"id":331233877,"uuid":"1125338573","full_name":"hiddenpath/ai-protocol","owner":"hiddenpath","description":"A data-driven registry and operator-based specification for normalizing AI models. Decouple providers from your code with a unified, versioned manifest.","archived":false,"fork":false,"pushed_at":"2026-02-03T17:07:01.000Z","size":293,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T06:26:33.683Z","etag":null,"topics":["ai","ai-infrastructure","cross-platform","json-schema","llm","manifest","protocol","standardization","yaml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hiddenpath.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T14:51:31.000Z","updated_at":"2026-02-03T17:08:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hiddenpath/ai-protocol","commit_stats":null,"previous_names":["hiddenpath/ai-protocol"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hiddenpath/ai-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddenpath%2Fai-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddenpath%2Fai-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddenpath%2Fai-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddenpath%2Fai-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hiddenpath","download_url":"https://codeload.github.com/hiddenpath/ai-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiddenpath%2Fai-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29124793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T14:05:12.718Z","status":"ssl_error","status_checked_at":"2026-02-05T14:03:53.078Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-infrastructure","cross-platform","json-schema","llm","manifest","protocol","standardization","yaml"],"created_at":"2026-01-06T01:09:01.363Z","updated_at":"2026-03-08T08:05:11.084Z","avatar_url":"https://github.com/hiddenpath.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI-Protocol: Data-State Rulebook\n\n**AI-Protocol is a provider-agnostic specification for all AI models, standardizing how we interact with intelligence, regardless of modality** (text, vision, audio, video). We decouple the \"data-state rulebook\" from the \"language-state runtime\" to provide unified infrastructure for the AI ecosystem.\n\n**We complement standards like [MCP](https://modelcontextprotocol.io) by providing a declarative runtime for raw API normalization.** While MCP focuses on high-level protocols for tool calling and context management, AI-Protocol focuses on standardizing and normalizing low-level API calls, enabling runtimes to uniformly handle APIs from different providers.\n\n## 🎯 Project Vision\n\n- **Data-State Rulebook**: Focuses on defining standardized interfaces and behavioral norms for AI models\n- **Language-State Runtime**: Focuses on implementing efficient, scalable AI model runtimes (like ai-lib-rust)\n- **Ecosystem Decoupling**: Protocol specifications are separated from implementations, supporting unified ecosystems across multiple languages and frameworks\n- **Provider-Agnostic**: Unifies APIs from different AI providers, enabling true cross-provider interoperability\n- **Cross-Modality Support**: Standardizes interactions across text, vision, audio, video, and other modalities\n\n## 📁 Project Structure\n\n```\nai-protocol/\n├── schemas/                    # JSON Schema validation specifications\n│   ├── v1.json                # v1.x provider/model configuration Schema\n│   ├── spec.json              # Specification file (spec.yaml) Schema\n│   └── v2/                    # V2 protocol schemas\n│       ├── provider.json      # V2 provider manifest schema (three-ring model)\n│       ├── capabilities.json  # Capability declaration schema\n│       ├── errors.json        # Standard error code definitions (13 codes)\n│       ├── endpoint.json      # Endpoint configuration schema\n│       ├── availability.json  # Availability schema\n│       ├── regions.json       # Region configuration schema\n│       ├── mcp.json           # MCP integration schema\n│       ├── computer-use.json  # Computer Use abstraction schema\n│       ├── multimodal.json    # Extended multimodal capabilities schema\n│       ├── provider-contract.json # Provider contract schema\n│       └── context-policy.json # Context management policy schema\n├── v1/                        # v1.x stable version specification\n│   ├── spec.yaml              # Basic specifications: standard parameters, event enumeration\n│   ├── providers/             # Provider configurations (split by vendor for easy PR)\n│   │   ├── openai.yaml        # OpenAI compatible interface\n│   │   ├── anthropic.yaml     # Anthropic Claude interface\n│   │   ├── gemini.yaml        # Google Gemini interface\n│   │   └── ...                # 30+ providers (see full list below)\n│   └── models/                # Model instance registry\n│       ├── gpt.yaml           # GPT series models\n│       ├── claude.yaml        # Claude series models\n│       └── ...                # More models\n├── v2/                        # v2 formal provider manifests\n│   └── providers/             # 6 V2 provider manifests (OpenAI, Anthropic, Google, etc.)\n├── v2-alpha/                  # v2-alpha experimental version\n│   └── spec.yaml              # Experimental operator definitions\n├── tests/                     # Cross-runtime compliance test suite\n│   └── compliance/            # YAML-defined test cases for Rust/Python consistency\n├── examples/                  # Configuration examples\n├── docs/                      # Documentation\n│   ├── V2_ARCHITECTURE.md     # V2 three-layer pyramid architecture design\n│   ├── SPEC.md                # Provider manifest specification\n│   └── ...                    # More documentation\n├── research/                  # Research documents (official API excerpts and verification)\n│   └── providers/             # Provider-specific official documentation research\n└── scripts/                   # Maintenance scripts\n```\n\n## 🔧 Core Concepts\n\n### 1. Operator-based Design\n\nAI-Protocol standardizes AI model behavior through the concept of **operators**:\n\n- **Parameter Operators**: Standardized parameter mapping (`temperature`, `max_tokens`, `stream`, etc.)\n- **Event Operators**: Standardized streaming events (`PartialContentDelta`, `ToolCallStarted`, `StreamError`, etc.)\n- **Capability Operators**: Standardized capability declarations (`chat`, `vision`, `tools`, `streaming`, `multimodal`, etc.)\n- **Error Handling Operators**: Standardized error classification, rate limiting, and retry strategies (`error_classification`, `retry_policy`, `rate_limit_headers`)\n\n### 2. Version Isolation\n\n- **v1.x**: Production environment stable version, supporting current mainstream AI models\n- **v2-alpha**: Experimental version, exploring multimodal streams, real-time instructions, and other cutting-edge features\n- **Schema Constraints**: Every configuration file is strictly validated through JSON Schema\n\n### 3. Modular Maintenance\n\n- **Provider Independence**: Each AI provider's configuration is maintained independently, facilitating community contributions\n- **Model Registration**: Model instances are registered as configuration files referencing provider definitions\n- **PR Friendly**: Modifying a single provider won't affect other configurations\n\n## 🚀 Quick Start\n\n### 1. Provider Configuration Example\n\n```yaml\n# v1/providers/anthropic.yaml\n$schema: \"https://raw.githubusercontent.com/hiddenpath/ai-protocol/main/schemas/v1.json\"\n\nid: anthropic\nprotocol_version: \"1.5\"\n\nstreaming:\n  decoder:\n    format: \"anthropic_sse\"\n    strategy: \"anthropic_event_stream\"\n\n  event_map:\n    - match: \"$.type == 'content_block_delta' \u0026\u0026 $.delta.type == 'text_delta'\"\n      emit: \"PartialContentDelta\"\n      extract:\n        content: \"$.delta.text\"\n```\n\n\u003e **Schema URL Best Practice**: You can pin the `$schema` URL to a specific release tag for version stability:\n\u003e - `https://raw.githubusercontent.com/hiddenpath/ai-protocol/v0.2.1/schemas/v1.json` (pinned to release)\n\u003e - `https://raw.githubusercontent.com/hiddenpath/ai-protocol/main/schemas/v1.json` (latest on main)\n\n### 2. Error Handling and Rate Limiting Example\n\n```yaml\n# v1/providers/openai.yaml (excerpt)\nerror_classification:\n  by_http_status:\n    \"400\": \"invalid_request\"\n    \"401\": \"authentication\"\n    \"429\": \"rate_limited\"  # Could be rate limit or quota exhausted\n    \"500\": \"server_error\"\n\nrate_limit_headers:\n  requests_limit: \"x-ratelimit-limit-requests\"\n  requests_remaining: \"x-ratelimit-remaining-requests\"\n  retry_after: null  # OpenAI doesn't use standard Retry-After\n\nretry_policy:\n  strategy: \"exponential_backoff\"\n  min_delay_ms: 1000\n  jitter: \"full\"\n  retry_on_http_status: [429, 500]\n  notes:\n    - \"429 may be rate limit or quota exhausted; runtimes should inspect error messages\"\n```\n\n### 3. Model Registration Example\n\n```yaml\n# v1/models/claude.yaml\n$schema: \"https://raw.githubusercontent.com/hiddenpath/ai-protocol/main/schemas/v1.json\"\n\nmodels:\n  claude-3-5-sonnet:\n    provider: anthropic\n    model_id: \"claude-3-5-sonnet-20241022\"\n    context_window: 200000\n    capabilities: [chat, vision, tools, streaming, agentic, reasoning]\n    pricing:\n      input_per_token: 0.000003\n      output_per_token: 0.000015\n```\n\n### 4. Runtime Integration\n\n```rust\n// Dynamic loading example in ai-lib-rust\nuse ai_lib_rust::protocol::ProtocolLoader;\n\n// By default, the loader prioritizes the `dist/` directory (JSON) for production efficiency,\n// falling back to `v1/` (YAML) for development convenience if JSON is missing.\nlet loader = ProtocolLoader::new();\nlet provider = loader.load_provider(\"anthropic\").await?;\nlet model = loader.load_model(\"anthropic/claude-3-5-sonnet\").await?;\n```\n\n## 📋 Validation and Testing\n\n```bash\n# Install dependencies\nnpm install\n\n# Run JSON Schema validation (all)\nnpm run validate\n\n# Run specific validations\nnpm run validate:providers   # Validate provider configs only\nnpm run validate:models      # Validate model configs only\nnpm run validate:examples    # Validate examples only\nnpm run validate:specs       # Validate spec files only\nnpm run validate:schemas     # Validate JSON schema syntax only\n\n# Execution governance automation\nnpm run drift:check          # Detect P0 provider/fixture/case drift\nnpm run gate:manifest-consumption   # Cross-repo latest-manifest consumption gate\nnpm run gate:compliance-matrix      # Cross-repo full compliance matrix gate\nnpm run gate:fullchain             # One-shot governance fullchain gate\nnpm run release:gate         # Evaluate release gate status\nnode scripts/drift-detect.js --report-only   # Advisory drift report (non-blocking)\nnode scripts/release-gate.js --report-only   # Advisory release gate report (non-blocking)\n```\n\nThe canonical validation script is `scripts/validate.js`, which uses AJV v8 with JSON Schema 2020-12 and ajv-formats.  \nExecution governance scripts:\n- `scripts/drift-detect.js`: verifies P0 provider readiness coverage across v2 manifests, compliance fixtures, and loading cases\n- `scripts/gate-manifest-consumption.js`: runs protocol + Rust/Python/TS latest-manifest consumption checks and writes gate report (`reports/manifest-gates/`)\n- `scripts/gate-compliance-matrix.js`: runs protocol + Rust/Python/TS compliance matrix checks and writes gate report (`reports/compliance-gates/`)\n- `scripts/gate-fullchain.js`: orchestrates drift + manifest + compliance + release gates in one run (`reports/fullchain-gates/`)\n- `scripts/release-gate.js`: computes pass/blocked decision from rollout metrics input (default: `scripts/release-gate-input.example.json`)\n- `report-only` mode (`--report-only`) is available for drift/release gates to support advisory CI rollout without immediate hard blocking\nOptional runtime model verification (document-first; no API keys required for the registry): see [docs/FACT_CHECKING_MODELS.md](docs/FACT_CHECKING_MODELS.md).\n\n## 📦 Build \u0026 Distribution\n\nAI-Protocol is distributed as pre-compiled JSON files to ensure runtime efficiency and zero-parsing overhead.\n\n```bash\n# Validate first, then build JSON artifacts\nnpm run validate\nnpm run build\n```\n\nBuild: run `npm run validate` first. This command then:\n1.  Cleans the `dist/` directory to remove stale files from previous builds.\n2.  Converts all YAML under `v1/`, `v2/`, and `v2-alpha/` into JSON in `dist/`.\n3.  Generates a `dist/index.json` manifest index with version information.\n\nRuntimes (like `ai-lib-rust`) should consume the `dist/` directory directly.\n\n### CI/CD Pipeline\n\nThe GitHub Actions workflow (`validate.yml`) automatically:\n- Validates all configurations using `npm ci` + `npm run validate`\n- Builds JSON artifacts using `npm run build`\n- Uploads the `dist/` folder as a build artifact\n- Runs additional yamllint checks for YAML style (non-blocking)\n- `governance-report.yml` runs drift/release gates in report-only mode and archives JSON evidence artifacts\n\nSee [docs/CI_VALIDATION_EXPLAINED.md](docs/CI_VALIDATION_EXPLAINED.md) for detailed CI documentation.\n\n## 🛣️ Roadmap\n\n### v1.x (Current Stable)\n- ✅ **30+ AI providers** supported across global and China regions\n- ✅ Standardized parameters and event normalization\n- ✅ Tool calling and streaming response support\n- ✅ JSON Schema constraints\n- ✅ Error handling and classification standardization (`error_classification`, 13 standard error classes)\n- ✅ Rate limiting and retry policy standardization (`rate_limit_headers`, `retry_policy`)\n- ✅ API family declarations (`api_families`, `endpoints`) to avoid request/response model confusion\n- ✅ Termination reason normalization (`termination_reasons`) unified across providers\n\n#### Supported Providers\n\n**Global Providers:**\n- OpenAI, Anthropic, Google Gemini, Groq, Mistral, Cohere, Perplexity\n- Together AI, DeepInfra, OpenRouter, Azure OpenAI, NVIDIA API Catalog (NVIDIA Build)\n- Fireworks AI, Replicate, AI21 Labs, Cerebras, Lepton AI\n\n**China Region Providers:**\n- Qwen (Alibaba), DeepSeek, Zhipu GLM\n- Doubao (ByteDance), Baidu ERNIE, iFlytek Spark\n- Tencent Hunyuan, SenseNova, Tiangong\n- Moonshot/Kimi, MiniMax, Baichuan, Yi\n- SiliconFlow\n\n### v2 (In Progress)\n- 🔄 **V2 Three-Layer Pyramid Architecture** (L1 Core / L2 Extensions / L3 Environment)\n- 🔄 **Unified Error Code System** — standardized error codes across all providers\n- 🔄 **Capability Declaration Mechanism** — structured `required`/`optional` capabilities\n- 🔄 **Feature Flag Mechanism** — load only what you need\n- 🔄 **STT / TTS / Rerank** — speech-to-text, text-to-speech, document reranking (OpenAI, Cohere, Jina)\n- 🔄 **Compliance Test Suite** — machine-verified cross-runtime consistency\n\n### v2-alpha (Experimental)\n- 🔄 Multimodal stream interleaving (`FrameInterleave` operator)\n- 🔄 Real-time instructions (`StateSync` operator)\n- 🔄 Schema-less mapping\n- 🔄 Advanced tool accumulation patterns\n\n### v2.x (Future Plans)\n- 📅 ProviderContract abstraction\n- 📅 CLI toolchain (`init`, `validate`, `convert`, `check-compat`)\n- 📅 WASM support for browser/Edge execution\n- 📅 Framework integrations (LangChain, LlamaIndex)\n\n## 🤝 Contribution Guide\n\n### Adding New Providers\n\n1. Create a new file under `v1/providers/` (e.g., `new-provider.yaml`)\n2. Follow JSON Schema specifications (`schemas/v1.json`)\n3. Add official documentation research under `research/providers/` (`new-provider.md`) with VERIFIED evidence\n4. Add corresponding model configurations under `v1/models/`\n5. Submit PR with test cases and validation results\n\n**All configurations are hosted in this repository**, where community contributions follow the same version control and validation process as official configurations.\n\n### Adding New Operators\n\n1. Define new operators in the corresponding version's `spec.yaml`\n2. Update JSON Schema\n3. Implement operator logic in runtime\n4. Add example configurations\n\n## 📄 License\n\nThis project is licensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.\n\n## 🔗 Related Projects \u0026 Runtime Installation\n\nAI-Protocol has official runtime implementations in multiple languages:\n\n### Python Runtime (v0.7.1)\n\n```bash\n# Install from PyPI\npip install ai-lib-python\n\n# Or with optional dependencies\npip install ai-lib-python[all]\n```\n\n```python\nfrom ai_lib import Client\n\n# Unified API across all providers\nclient = Client(provider=\"openai\")\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n```\n\n📦 **PyPI**: [ai-lib-python](https://pypi.org/project/ai-lib-python/) | 📖 **Docs**: [github.com/hiddenpath/ai-lib-python](https://github.com/hiddenpath/ai-lib-python)\n\n### Rust Runtime (v0.8.1)\n\n```toml\n# Add to Cargo.toml\n[dependencies]\nai-lib-rust = \"0.8.1\"\n```\n\n```rust\nuse ai_lib_rust::Client;\n\n// Unified API across all providers\nlet client = Client::new(\"anthropic\")?;\nlet response = client.chat()\n    .model(\"claude-3-5-sonnet-20241022\")\n    .message(\"user\", \"Hello!\")\n    .send()\n    .await?;\n```\n\n📦 **Crates.io**: [ai-lib-rust](https://crates.io/crates/ai-lib-rust) | 📖 **Docs**: [github.com/hiddenpath/ai-lib-rust](https://github.com/hiddenpath/ai-lib-rust)\n\n### ai-protocol-mock (v0.1.3)\n\nUnified mock server for testing runtimes without real API calls. Provides manifest-driven HTTP mock (OpenAI/Anthropic formats), STT/TTS/Rerank endpoints, and MCP JSON-RPC mock.\n\n```bash\n# Start mock server\ncd ai-protocol-mock \u0026\u0026 docker-compose up -d\n\n# Use with runtimes\nMOCK_HTTP_URL=http://localhost:4010 pytest tests/  # ai-lib-python\nMOCK_HTTP_URL=http://localhost:4010 cargo test -- --ignored  # ai-lib-rust\n```\n\n📖 **Repo**: [github.com/hiddenpath/ai-protocol-mock](https://github.com/hiddenpath/ai-protocol-mock)\n\n### Ecosystem Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      AI-Protocol                            │\n│            (Provider-agnostic Specification)                │\n├─────────────────────────────────────────────────────────────┤\n│  schemas/     │  v1/providers/  │  v1/models/              │\n│  JSON Schema  │  30+ Providers  │  Model Registry          │\n└───────────────┴────────────────┴───────────────────────────┘\n                          │\n            ┌─────────────┼─────────────┬─────────────┐\n            ▼             ▼             ▼             ▼\n    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐\n    │ ai-lib-rust  │ │ai-lib-python │ │ai-protocol-  │ │  Your App    │\n    │   (Rust)     │ │  (Python)    │ │mock (tests)  │ │   (Any)      │\n    └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘\n```\n\n\u003e **Note**: AI-Protocol itself already includes configuration registry functionality. Community contributions for new provider configurations and model registrations can be submitted directly via PRs to this repository's `v1/providers/` and `v1/models/` directories, without needing a separate configuration repository.\n\n---\n\n**AI-Protocol** abstracts the complexity of AI models into standardized protocols, allowing developers to focus on business logic rather than provider adaptation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiddenpath%2Fai-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhiddenpath%2Fai-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiddenpath%2Fai-protocol/lists"}