{"id":47630779,"url":"https://github.com/aiperceivable/apcore","last_synced_at":"2026-04-05T05:01:49.310Z","repository":{"id":338367587,"uuid":"1153471895","full_name":"aiperceivable/apcore","owner":"aiperceivable","description":"A schema-enforced module framework where every interface is inherently perceivable by AI.","archived":false,"fork":false,"pushed_at":"2026-03-31T14:04:24.000Z","size":811,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T07:37:01.870Z","etag":null,"topics":["access-control","ai","ai-agent","ai-agent-framework","api-specifications","developer-tools","executor","governance","middleware","module-system","observability","plugin-architecture","registry","schema"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aiperceivable.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-09T10:40:53.000Z","updated_at":"2026-03-31T14:04:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aiperceivable/apcore","commit_stats":null,"previous_names":["aipartnerup/apcore","aiperceivable/apcore"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/aiperceivable/apcore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiperceivable%2Fapcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiperceivable%2Fapcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiperceivable%2Fapcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiperceivable%2Fapcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aiperceivable","download_url":"https://codeload.github.com/aiperceivable/apcore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiperceivable%2Fapcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31424931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"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":["access-control","ai","ai-agent","ai-agent-framework","api-specifications","developer-tools","executor","governance","middleware","module-system","observability","plugin-architecture","registry","schema"],"created_at":"2026-04-01T23:28:08.656Z","updated_at":"2026-04-05T05:01:49.261Z","avatar_url":"https://github.com/aiperceivable.png","language":"Shell","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./apcore-logo.svg\" alt=\"apcore logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n# apcore — AI-Perceivable Core\n\n\u003e **AI-Perceivable**: When modules, interfaces, and tools are clearly perceived by AI, the model can understand their structure and purpose, and therefore know exactly how to invoke, orchestrate, and act on them. From perception → cognition → execution.\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12294/badge)](https://www.bestpractices.dev/projects/12294)\n[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/aiperceivable/apcore-python)\n[![TypeScript Version](https://img.shields.io/badge/TypeScript-Node_18%2B-blue)](https://github.com/aiperceivable/apcore-typescript)\n[![Rust Version](https://img.shields.io/badge/Rust-1.75%2B-blue)](https://github.com/aiperceivable/apcore-rust)\n\n\n\n\u003e **Build once, invoke by Code or AI.**\n\nA schema-enforced module standard for the AI-Perceivable era.\n\napcore is an **AI-Perceivable module standard** that makes every interface naturally perceivable and understandable by AI through enforced Schema definitions and behavioral annotations.\n\n**apcore is a protocol specification.** Language implementations are maintained in separate repositories:\n\n| SDK | Language | Install | Repository |\n|-----|----------|---------|------------|\n| **apcore** | Python | `pip install apcore` | [github.com/aiperceivable/apcore-python](https://github.com/aiperceivable/apcore-python) |\n| **apcore-js** | TypeScript | `npm install apcore-js` | [github.com/aiperceivable/apcore-typescript](https://github.com/aiperceivable/apcore-typescript) |\n| **apcore** | Rust | `cargo add apcore` | [github.com/aiperceivable/apcore-rust](https://github.com/aiperceivable/apcore-rust) |\n\n---\n\n## Table of Contents\n\n- [What is apcore?](#what-is-apcore)\n  - [The Concept: Cognitive Interface](#the-concept-cognitive-interface)\n  - [Why Not Just Use Existing MCP Solutions?](#why-not-just-use-existing-mcp-solutions)\n- [Why AI-Perceivable?](#why-ai-perceivable)\n  - [The AI Collaboration Lifecycle](#the-ai-collaboration-lifecycle)\n- [Core Principles](#core-principles)\n- [Architecture Overview](#architecture-overview)\n- [Quick Start](#quick-start)\n- [Module Development](#module-development)\n  - [Two Integration Paths](#two-integration-paths)\n  - [Class-based Modules](#1-class-based-modules)\n  - [@module Decorator](#2-module-decorator)\n  - [module() Function Call](#3-module-function-call)\n  - [External Binding (Zero Code Modification)](#4-external-binding-zero-code-modification)\n- [Schema System](#schema-system)\n  - [Three-Layer Metadata Design](#three-layer-metadata-design)\n  - [Module Annotations](#module-annotations)\n  - [LLM Extension Fields](#llm-extension-fields)\n- [Context Object](#context-object)\n- [ACL Access Control](#acl-access-control)\n- [Middleware](#middleware)\n- [Configuration](#configuration)\n- [Observability](#observability)\n- [Error Handling \u0026 AI Guidance](#error-handling--ai-guidance)\n- [Cross-Language Support](#cross-language-support)\n- [Relationship with Other Tools](#relationship-with-other-tools)\n- [Implementations](#implementations)\n- [Ecosystem](#ecosystem)\n- [Documentation Index](#documentation-index)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What is apcore?\n\napcore is an **AI-Perceivable module standard** that makes every module naturally perceivable and understandable by AI through enforced Schema definitions.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                apcore — AI-Perceivable Core                 │\n│                                                             │\n│  AI-Perceivable module standard + Enforced Schema          │\n│  - Directory as ID (zero-config module discovery)          │\n│  - Schema-driven (input/output mandatory)                  │\n│  - ACL / Observability / Middleware                        │\n└─────────────────────────────────────────────────────────────┘\n                            ↓ Modules callable by\n      ┌──────────┬──────────┬──────────┬──────────┐\n      │          │          │          │          │\n  Legacy Code  AI/LLM    HTTP API    CLI Tool   MCP Server\n   (import)  (understands) (REST)    (terminal)  (Claude)\n```\n\n**Not just an AI framework, but a module standard that is naturally AI-Perceivable.**\n\n### The Concept: Cognitive Interface\n\nTraditional software provides **UI** for humans and **API** for programs. apcore provides the **Cognitive Interface** for AI Agents:\n- **Intent-Oriented**: AI thinks in \"What to do\" (Intents), not \"Which endpoint to call\".\n- **Strict Contracts**: Mandatory schemas ensure AI uses your tools correctly every time.\n- **Behavioral Personality**: Annotations like `readonly` and `destructive` guide Agent decisions.\n\n### Why Not Just Use Existing MCP Solutions?\n\nToday, many projects build their own MCP servers independently — Stripe has one, TipTap has one, NestJS has one. Each uses different interfaces, different standards, and none provides a programmable SDK. The result is a fragmented ecosystem where developers must learn a new approach for every integration.\n\napcore takes a different path: **SDK-first, standard-unified**.\n\n| | Fragmented MCP Solutions | apcore |\n|---|---|---|\n| **Programmable SDK** | No — only MCP servers | Yes — `apcore-python`, `apcore-typescript` |\n| **Unified Standard** | No — each project rolls its own | Yes — same schema, annotations, ACL across all integrations |\n| **Behavioral Annotations** | None or minimal | `readonly`, `destructive`, `requires_approval`, `idempotent`, `open_world` |\n| **Access Control** | None | Pattern-based ACL with role support |\n| **Audit Trail** | None | Built-in tracing, metrics, structured logging |\n| **Cross-Language** | Per-language silos | Python and TypeScript with identical behavior |\n\n### Core Problem\n\nTraditional module development faces a fundamental contradiction:\n\n```\nTraditional modules: Code can call, but AI cannot understand\nAI-Perceivable modules: Code can call, AI can also perceive and understand\n```\n\nAI has become an important caller in software systems, but most modules lack AI-understandable metadata. apcore fundamentally solves this by **enforcing** `input_schema` / `output_schema` / `description`.\n\n### One-Sentence Summary\n\n\u003e apcore solves **how to build modules** (module standard), not how to call tools (communication protocol).\n\u003e Once modules are built, they can be called by code / AI / HTTP / CLI / MCP or any other means.\n\n---\n\n## Why AI-Perceivable?\n\n\u003e Once perceived by the AI, it becomes understood, and the AI knows exactly how to act.\n\n**Perceivable by AI → Understandable by AI → Usable by AI**\n\n| Stage | Meaning | apcore Mechanism |\n|-------|---------|-----------------|\n| **Perceived** | AI can discover and read the module | Schema-enforced `description`, `input_schema`, `output_schema` |\n| **Understood** | AI knows *when* and *how* to use it | Behavioral annotations (`x-when-to-use`, `x-common-mistakes`) |\n| **Executed** | AI invokes it correctly and recovers from errors | `ai_guidance`, `requires_approval`, self-healing |\n\n### The AI Collaboration Lifecycle\n\napcore organizes module metadata into a coherent lifecycle that guides an Agent through every stage of a task:\n\n1.  **Discovery (Identity) — `description`**: Helps the Agent find the right tool for its intent.\n2.  **Strategy (Wisdom) — `metadata`**: Teaches the Agent *when* and *how* to use the tool correctly (e.g., `x-when-to-use`, `x-common-mistakes`).\n3.  **Governance (Safety) — `requires_approval`**: Sets the safety boundary for sensitive operations.\n4.  **Recovery (Resilience) — `ai_guidance`**: Provides a clear path for the Agent to fix errors autonomously.\n\n### Real-World Scenarios\n\n| Scenario | Without apcore | With apcore |\n|------|------------|------------|\n| LLM calling your business functions | Manually write tool descriptions, map parameters | Schema auto-provided, LLM understands directly |\n| New team members onboarding | Read source code, guess parameters | Clear from Schema + annotations |\n| Cross-team module reuse | Outdated docs, unclear interfaces | Schema is doc, enforced validation |\n| Security audit | Manually trace call relationships | ACL + call chain auto-tracked |\n| Expose as MCP Server | Rewrite interface definitions | Adapter reads Schema directly |\n\n### Design Decision\n\n```\nReality: AI has become a key caller in software systems\nDecision: Enforce input_schema / output_schema / description\nResult: Modules understandable by both humans and AI, no extra cost\n```\n\n---\n\n## Core Principles\n\n| Principle | Description |\n|------|------|\n| **Schema-Driven** | All modules enforce `input_schema` / `output_schema` / `description` |\n| **Directory as ID** | Directory path auto-maps to module ID, zero config |\n| **AI-Perceivable** | Schema enables AI/LLM perception and understanding—a design requirement, not optional |\n| **Universal Standard** | Modules callable by code/AI/HTTP/CLI or any other means |\n| **Progressive Integration** | Existing code gains AI-Perceivable capability via decorators, function calls, or YAML binding |\n| **Cross-Language Spec** | Language-agnostic protocol specification, any language can implement conformant SDK |\n\n### Differences from Traditional Frameworks\n\n| | Traditional Frameworks | apcore |\n|---|---------|--------|\n| **Schema** | Optional | **Enforced** |\n| **AI-Perceivable** | Not guaranteed | **Guaranteed** |\n| **Module Discovery** | Manual registration | Auto-discovery from directory |\n| **Input Validation** | Implement yourself | Framework automatic |\n| **Behavior Annotations** | None | `readonly` / `destructive` / `requires_approval` etc. |\n| **Call Tracing** | Implement yourself | `trace_id` auto-propagated |\n\n---\n\n## Architecture Overview\n\napcore's architecture consists of two orthogonal dimensions: **Framework Technical Architecture** (vertical) and **Business Layering Recommendations** (horizontal).\n\n### Framework Technical Architecture (Vertical)\n\nThe technical layers of the standard itself, defining the complete flow from module registration to execution:\n\n```\n┌─────────────────────────────────────────────────┐\n│      Application Layer                          │\n│   HTTP API / CLI / MCP Server / Custom Interface│\n└─────────────────────┬───────────────────────────┘\n                      ↓ calls\n┌─────────────────────────────────────────────────┐\n│      Execution Layer                            │\n│  ACL check → Input validation → Middleware chain│\n│  → Execute → Output validation                  │\n└──────────┬──────────────────────────────────────┘\n           ↓ lookup module\n┌─────────────────────────────────────────────────┐\n│      Registry Layer                             │\n│  Scan \u0026 discover → ID mapping → Interface       │\n│  validation → Module storage                    │\n└──────────┬──────────────────────────────────────┘\n           ↓ read\n┌─────────────────────────────────────────────────┐\n│      Module Layer                               │\n│  User-written business modules (conforming to   │\n│  Module interface specification)                │\n└─────────────────────────────────────────────────┘\n```\n\n### Business Layering Recommendations (Horizontal)\n\nUnder the `extensions/` directory, modules should be organized by responsibility (enforced by ACL):\n\n```\nextensions/\n├── api/                    # API Layer: Handle external requests\n│   └── ACL: Can only call orchestrator.*\n│\n├── orchestrator/           # Orchestration Layer: Compose business flows\n│   └── ACL: Can only call executor.* and common.*\n│\n├── executor/               # Execution Layer: Concrete business operations\n│   └── ACL: Can call common.*, can connect to external systems\n│\n└── common/                 # Common Layer: Shared utilities and helpers\n    └── ACL: Read-only operations, called by all layers\n```\n\n**Key Points**:\n- Framework technical architecture (Application → Execution → Registry → Module) is apcore's **implementation mechanism**\n- Business layering (api → orchestrator → executor → common) is a **best practice recommendation**, enforced through ACL configuration\n- The two are orthogonal: any business layer module (api/orchestrator/executor/common) goes through the same framework layer processing\n\n### Execution Flow\n\nA module call goes through a rigorous **Execution Pipeline**:\n\n```\nexecutor.call(\"executor.email.send_email\", inputs, context)\n   │\n   ├─  1.  Context processing: Create/update call context (trace_id, caller_id, call_chain)\n   ├─  2.  Safety checks: Verify call depth and detect circular calls\n   ├─  3.  Lookup module: Find target module from Registry\n   ├─  4.  ACL check: Verify caller has permission to call target module\n   ├─  5.  Approval Gate: Check requires_approval, await human decision\n   ├─  6.  Input validation: Validate input parameters against input_schema\n   ├─  7.  Middleware before: Execute middleware before() hooks in sequence\n   ├─  8.  Module execution: Call module.execute(inputs, context)\n   ├─  9.  Output validation: Validate output result against output_schema\n   ├─ 10.  Middleware after: Execute middleware after() hooks in reverse order\n   ├─ 11.  Return result\n   │\n   └─ (on error: middleware on_error hooks in reverse order)\n```\n\n### Directory as ID\n\nModule IDs are automatically generated from relative paths under the **module root directory** (default root is `extensions/`, multiple roots can be configured):\n\n```\nFile path:                                   Canonical ID:\nextensions/api/handler/user.py           →  api.handler.user\nextensions/executor/email/send_email.py  →  executor.email.send_email\nextensions/common/util/validator.py      →  common.util.validator\n\nRules:\n1. Remove module root prefix (default `extensions/`)\n2. Remove file extension\n3. Replace `/` with `.`\n4. Must match: ^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$\n5. Maximum length: 128 characters\n\n**Multiple Roots and Namespaces**\n\n- If multiple module root directories are configured, each root directory automatically uses the directory name as a **namespace**, ensuring Module ID uniqueness within the same Registry.\n- For example: `extensions_roots: [\"./extensions\", \"./plugins\"]` → `extensions.executor.email.send_email`, `plugins.my_tool`.\n- Automatic namespacing can be overridden with explicit configuration (e.g., `{root: \"./extensions\", namespace: \"core\"}` → `core.executor.email.send_email`).\n- Single root mode has no namespace by default (backward compatible); in multi-root mode, at most one root can set `namespace: \"\"` to omit the prefix.\n\n**Cross-Project Conflicts**\n\n- Same IDs from different projects **will not conflict**, unless they are merged into the same Registry / call domain (e.g., unified gateway or shared executor).\n```\n\n---\n\n## Quick Start\n\nFor a detailed multi-language guide, visit the **[Getting Started Guide](https://aiperceivable.github.io/apcore/getting-started.html)**.\n\n=== \"Python\"\n\n    ```bash\n    pip install apcore\n    ```\n\n    ```python\n    import apcore\n\n    # Use the global client for easy registration and calling\n    @apcore.module(id=\"math.add\", description=\"Add two integers\")\n    def add(a: int, b: int) -\u003e int:\n        return a + b\n\n    # Call directly\n    print(apcore.call(\"math.add\", {\"a\": 10, \"b\": 5}))  # {'result': 15}\n    ```\n\n    Or use the explicit client:\n\n    ```python\n    from apcore import APCore\n\n    client = APCore()\n\n    @client.module(id=\"math.add\")\n    def add(a: int, b: int) -\u003e int:\n        return a + b\n\n    print(client.call(\"math.add\", {\"a\": 10, \"b\": 5}))\n    ```\n\n=== \"TypeScript\"\n\n    ```bash\n    npm install apcore-js\n    ```\n\n    ```typescript\n    import { Type } from '@sinclair/typebox';\n    import { FunctionModule, Registry, Executor } from 'apcore-js';\n\n    const add = new FunctionModule({\n      moduleId: 'math.add',\n      description: 'Add two numbers',\n      inputSchema: Type.Object({ a: Type.Number(), b: Type.Number() }),\n      outputSchema: Type.Object({ sum: Type.Number() }),\n      execute: (inputs) =\u003e ({ sum: (inputs.a as number) + (inputs.b as number) }),\n    });\n\n    const registry = new Registry();\n    registry.register('math.add', add);\n    const executor = new Executor({ registry });\n    console.log(await executor.call('math.add', { a: 10, b: 5 })); // { sum: 15 }\n    ```\n\n### Project Directory Structure\n\n```\nmy-project/\n├── apcore.yaml               # Framework configuration\n├── extensions/               # Module directory (directory path = module ID)\n│   ├── api/                  # API layer\n│   ├── orchestrator/         # Orchestration layer\n│   └── executor/             # Execution layer\n├── schemas/                  # Schema definitions (YAML, shared across languages)\n└── acl/                      # Permission configuration\n```\n\n---\n\n## Module Development\n\n\u003e Detailed definitions: [Module Interface](./docs/api/module-interface.md) | [Creating Modules Guide](./docs/guides/creating-modules.md)\n\n### Two Integration Paths\n\n1.  **Native SDK (Recommended)**: Best for new projects. Full type safety and lifecycle control.\n2.  **Zero-Intrusion Patch**: Best for legacy code. Upgrade via decorators or YAML bindings **without rewriting business logic**.\n\n### Implementation Approaches\n\napcore provides four ways to define modules, suitable for different scenarios:\n\n#### 1. Class-based Modules\n\nThe most complete approach, supporting all features:\n\n```python\n# extensions/executor/email/send_email.py\n# Module ID auto-generated: executor.email.send_email\n\nfrom apcore import Module, ModuleAnnotations, Context\nfrom pydantic import BaseModel, Field\n\nclass SendEmailInput(BaseModel):\n    \"\"\"LLM understands what parameters are needed through this Schema\"\"\"\n    to: str = Field(..., description=\"Recipient email address\")\n    subject: str = Field(..., description=\"Email subject\")\n    body: str = Field(..., description=\"Email body\")\n\nclass SendEmailOutput(BaseModel):\n    \"\"\"LLM understands what is returned through this Schema\"\"\"\n    success: bool\n    message_id: str = None\n\nclass SendEmailModule(Module):\n    \"\"\"Send email module\n\n    Detailed documentation:\n    - Supports text and HTML format emails\n    - Uses SMTP protocol to connect to external mail server\n    - Configuration items: smtp_host, smtp_port, smtp_user, smtp_pass\n\n    Usage example:\n      Input: {\"to\": \"user@example.com\", \"subject\": \"Hello\", \"body\": \"World\"}\n      Output: {\"success\": true, \"message_id\": \"msg_123\"}\n\n    Notes:\n    - SMTP server information must be configured in the configuration file\n    - Gmail limits 500 emails/day, other providers may have different limits\n    - EmailSendError exception will be raised on send failure\n    \"\"\"\n\n    # Core layer (must be defined)\n    input_schema = SendEmailInput\n    output_schema = SendEmailOutput\n    description = \"Send email to specified recipient. Uses SMTP protocol, non-idempotent operation, requires mail server configuration.\"\n\n    # Optional: Detailed documentation (for complex modules)\n    documentation = \"\"\"\n# Features\nSend emails via SMTP protocol, supporting plain text and HTML formats.\n\n## Configuration Requirements\n- SMTP server information must be configured in apcore.yaml\n- Valid SMTP authentication credentials required\n\n## Use Cases\n- Send notification emails, verification codes, reports\n\n## Limitations\n- Gmail: 500 emails/day\n- Attachment size: ≤25MB\n\"\"\"\n\n    # Annotation layer (optional, type-safe)\n    annotations = ModuleAnnotations(\n        readonly=False,        # Has side effects\n        destructive=False,     # Won't delete/overwrite data\n        idempotent=False,      # Repeated calls will send repeatedly\n        requires_approval=True, # Requires user confirmation\n        open_world=True,       # Connects to external system (SMTP)\n    )\n    tags = [\"email\", \"notification\"]\n\n    def execute(self, inputs: dict, context: Context) -\u003e dict:\n        validated = SendEmailInput(**inputs)\n        # ... send email logic ...\n        return SendEmailOutput(success=True, message_id=\"msg_123\").model_dump()\n```\n\n**This module automatically has:**\n- LLM-understandable Schema and behavior annotations\n- Auto-generated ID (`executor.email.send_email`)\n- Input/output validation\n- Call chain tracing, observability\n\n#### 2. @module Decorator\n\nSuitable for scenarios where **source code can be modified**, one-line integration:\n\n```python\n# Before: Plain function\ndef send_email(to: str, subject: str, body: str) -\u003e dict:\n    \"\"\"Send email\"\"\"\n    return {\"success\": True, \"message_id\": \"msg_123\"}\n\n# After: Add one line decorator, automatically becomes an apcore module\nfrom apcore import module\n\n@module(id=\"email.send\", tags=[\"email\"])\ndef send_email(to: str, subject: str, body: str) -\u003e dict:\n    \"\"\"Send email\"\"\"\n    return {\"success\": True, \"message_id\": \"msg_123\"}\n# Schema automatically inferred from type annotations\n```\n\n#### 3. module() Function Call\n\nSuitable for scenarios where **you don't want to modify source code**, completely non-invasive to existing code:\n\n```python\nfrom apcore import module\n\n# Existing business code, no modification needed\nclass EmailService:\n    def send(self, to: str, subject: str, body: str) -\u003e dict:\n        \"\"\"Send email\"\"\"\n        return {\"success\": True}\n\nservice = EmailService()\nmodule(service.send, id=\"email.send\")  # Register as apcore module\n```\n\n#### 4. External Binding (Zero Code Modification)\n\nSuitable for scenarios where **source code cannot be modified** (third-party libraries, legacy systems, etc.), pure YAML configuration:\n\n```yaml\n# bindings/email.binding.yaml\nbindings:\n  - module_id: \"email.send\"\n    target: \"myapp.services.email:send_email\"   # Callable object path\n    description: \"Send email\"\n    auto_schema: true     # Auto-generate Schema from type annotations\n    annotations:\n      open_world: true\n      requires_approval: true\n    tags: [\"email\"]\n```\n\n#### Comparison of Four Approaches\n\n| Approach | Code Invasiveness | Use Case | Schema Definition |\n|------|-----------|---------|------------|\n| Class-based | High (write new class) | New module development | Manual definition (most complete) |\n| `@module` Decorator | Low (add one line) | Modifiable code | Inferred from type annotations |\n| `module()` Function Call | Very low (don't modify original function) | Existing classes/methods | Inferred from type annotations |\n| External Binding | Zero | Cannot modify source code scenarios | Auto-inferred or manually specified |\n\n---\n\n## Schema System\n\n\u003e Detailed definitions: [Schema Definition Guide](./docs/guides/schema-definition.md) | [ModuleAnnotations API](./docs/api/module-interface.md#34-annotations)\n\n### Three-Layer Metadata Design\n\nEach module's metadata is divided into three layers, progressing from required to optional:\n\n```\n┌──────────────────────────────────────────────────┐\n│ Core Layer (REQUIRED)                            │\n│ input_schema / output_schema / description       │\n│ → AI understands \"what this module does\"         │\n│                                                  │\n│ + documentation (OPTIONAL, detailed docs)        │\n│ → AI understands \"detailed use cases and         │\n│   constraints\"                                   │\n├──────────────────────────────────────────────────┤\n│ Annotation Layer (OPTIONAL, type-safe)           │\n│ annotations / examples / tags / version          │\n│ → AI understands \"how to use correctly\"          │\n├──────────────────────────────────────────────────┤\n│ Extension Layer (OPTIONAL, free dictionary)      │\n│ metadata: dict[str, Any]                         │\n│ → Custom requirements (framework doesn't         │\n│   validate); AI tactical wisdom                  │\n│   (x-when-to-use, etc.) also lives here          │\n└──────────────────────────────────────────────────┘\n```\n\n### Description and Documentation Fields\n\n**Borrowing from Claude Skill's Progressive Disclosure design, apcore uses two fields to organize module documentation:**\n\n| Field | Required | Length Limit | Markdown | Purpose |\n|------|--------|----------|----------|------|\n| `description` | **Required** | ≤200 characters | No | Brief module function description for AI quick matching and understanding |\n| `documentation` | Optional | ≤5000 characters | Yes | Detailed documentation including use cases, constraints, configuration requirements |\n\n- **Module discovery phase**: AI reads all modules' `description`, quickly determines candidate modules\n- **Call decision phase**: AI loads `documentation` on-demand, learns detailed usage and constraints\n\n\u003e Complete format rules and correspondence with Claude Skill / OpenAPI: see [Protocol Specification §4.8](./PROTOCOL_SPEC.md#48-description-and-documentation). Code examples: see [Class-based Modules](#1-class-based-modules) above.\n\n### Schema Definition\n\nSchema is based on **JSON Schema Draft 2020-12**, supports YAML format definition (shared across languages). Schema files are placed in the `schemas/` directory, with paths corresponding to module IDs.\n\n\u003e Complete Schema format and YAML examples: see [Schema Definition Guide](./docs/guides/schema-definition.md) | [Protocol Specification §4](./PROTOCOL_SPEC.md#4-schema-specification).\n\n### Module Annotations\n\nAnnotations describe module **behavior characteristics**, helping AI make safer call decisions:\n\n| Annotation | Type | Description | AI Behavior Impact |\n|------|------|------|------------|\n| `readonly` | bool | No side effects, read-only operation | AI can safely call autonomously |\n| `destructive` | bool | May delete or overwrite data | AI should request user confirmation before calling |\n| `idempotent` | bool | Repeated calls have same result | AI can safely retry |\n| `requires_approval` | bool | Requires explicit user consent | AI must wait for human approval (enforced by Executor) |\n| `open_world` | bool | Connects to external systems | AI should inform user of external interaction |\n| `streaming` | bool | Supports streaming execution | AI can use streaming response mode |\n| `cacheable` | bool | Output can be cached | AI can reuse previous results within `cache_ttl` |\n| `cache_ttl` | int | Cache duration in seconds | AI knows how long cached results remain valid |\n| `paginated` | bool | Returns paginated results | AI knows to pass cursor/offset and expect partial results |\n| `cache_key_fields` | list[str] | Input fields used as cache key | AI knows which inputs affect caching |\n| `pagination_style` | str | Pagination style: `cursor`, `offset`, or `page` | AI knows which pagination parameters to use |\n\n```python\n# Read-only query - AI can call autonomously\nannotations = ModuleAnnotations(readonly=True)\n\n# Delete operation - AI needs to request confirmation\nannotations = ModuleAnnotations(destructive=True, requires_approval=True)\n\n# External API call - AI needs to inform user\nannotations = ModuleAnnotations(open_world=True, idempotent=True)\n\n# Cacheable query with 5-minute TTL\nannotations = ModuleAnnotations(readonly=True, cacheable=True, cache_ttl=300)\n\n# Paginated list endpoint\nannotations = ModuleAnnotations(readonly=True, paginated=True, pagination_style=\"cursor\")\n```\n\n### LLM Extension Fields\n\nFields with `x-` prefix in Schema are LLM-specific extensions, don't affect standard JSON Schema validation:\n\n| Field | Description | Example |\n|------|------|------|\n| `x-llm-description` | Extended description for LLM (more detailed than description) | `\"User's login password, at least 8 characters\"` |\n| `x-examples` | Example values to help LLM understand format | `[\"user@example.com\"]` |\n| `x-sensitive` | Mark sensitive fields (password, API Key, etc.) | `true` |\n| `x-constraints` | Business constraints described in natural language | `\"Must be a registered user\"` |\n| `x-deprecated` | Deprecation information | `{\"since\": \"2.0\", \"use\": \"new_field\"}` |\n\n\u003e Complete usage and examples: see [Schema Definition Guide](./docs/guides/schema-definition.md) | [Protocol Specification §4.3](./PROTOCOL_SPEC.md#43-llm-extension-fields).\n\n### AI Metadata Conventions\n\nIn the extension layer (`metadata` dictionary), you can provide optional AI metadata to help agents understand *when*, *how*, and *at what cost* to use the module. These are conventions, not enforced by the framework.\n\n**Intent \u0026 Planning:**\n\n| Key | Purpose |\n|-----|---------|\n| `x-when-to-use` | Positive guidance: scenarios where this module is the right choice |\n| `x-when-not-to-use` | Negative guidance: scenarios where a different module should be used |\n| `x-common-mistakes` | Known pitfalls that AI agents frequently encounter |\n| `x-workflow-hints` | Suggested pre/post steps or related modules in a typical workflow |\n| `x-preconditions` | What must be true before calling (e.g., \"User must be authenticated\") |\n| `x-postconditions` | What will be true after successful execution |\n| `x-side-effects` | External state changes caused by this module |\n\n**Performance, Cost \u0026 Trust:**\n\n| Key | Purpose |\n|-----|---------|\n| `x-cost-per-call` | Estimated cost per invocation |\n| `x-avg-latency-ms` | Average execution latency in milliseconds |\n| `x-max-latency-ms` | Maximum expected latency in milliseconds |\n| `x-sla` | SLA targets (availability, latency percentiles) |\n| `x-output-source` | Data provenance: `database`, `api`, `generated`, `cached`, `computed` |\n| `x-verification-hint` | How to cross-check the output for correctness |\n\n\u003e Detailed usage: see [Protocol Specification §4.6](./PROTOCOL_SPEC.md#46-module-extension-metadata-metadata).\n\n---\n\n## Context Object\n\nContext is the execution context that runs through the entire call chain, carrying tracing, permissions, and shared data:\n\n```python\nclass Context:\n  trace_id: str           # Call trace ID (UUID v4; W3C trace-id compatible in distributed scenarios)\n    caller_id: str | None   # Caller module ID (None for top-level calls)\n    call_chain: list[str]   # Call chain (accumulated in call order)\n    executor: Executor      # Executor reference (entry point for inter-module calls)\n    identity: Identity      # Caller identity\n    data: dict              # Shared data (reference-shared within call chain)\n```\n\n### Call Chain Propagation\n\n```python\n# Top-level call\ncontext = Context(trace_id=\"abc-123\", identity=Identity(id=\"user_1\", roles=[\"admin\"]))\n\n# Module A is called\n#   trace_id: \"abc-123\"        ← Stays the same\n#   caller_id: None            ← No caller at top level\n#   call_chain: [\"module_a\"]\n\n# Module A internally calls Module B\nresult = context.executor.call(\"module_b\", inputs, context)\n#   trace_id: \"abc-123\"        ← Stays the same\n#   caller_id: \"module_a\"      ← Caller is module_a\n#   call_chain: [\"module_a\", \"module_b\"]\n\n# Module B internally calls Module C\n#   trace_id: \"abc-123\"        ← Same trace_id for entire chain\n#   caller_id: \"module_b\"\n#   call_chain: [\"module_a\", \"module_b\", \"module_c\"]\n```\n\n**Key Feature:** `context.data` is **reference-shared** throughout the entire call chain, allowing modules to pass intermediate results and implement pipeline-style data flow.\n\n---\n\n## ACL Access Control\n\n\u003e Detailed definitions: [ACL Configuration Guide](./docs/guides/acl-configuration.md) | [Protocol Specification §6](./PROTOCOL_SPEC.md#6-acl-specification)\n\nACL (Access Control List) controls which modules can call which modules, default deny:\n\n```yaml\n# acl/global_acl.yaml\nrules:\n  # API layer can only call orchestration layer\n  - callers: [\"api.*\"]\n    targets: [\"orchestrator.*\"]\n    effect: allow\n\n  # Orchestration layer can call execution layer\n  - callers: [\"orchestrator.*\"]\n    targets: [\"executor.*\"]\n    effect: allow\n\n  # Forbid cross-layer calls (API directly calling execution layer)\n  - callers: [\"api.*\"]\n    targets: [\"executor.*\"]\n    effect: deny\n\n  # System internal modules unrestricted\n  - callers: [\"@system\"]\n    targets: [\"*\"]\n    effect: allow\n\ndefault_effect: deny  # Default deny when no rules match\n\naudit:\n  enabled: true\n  log_level: info\n  include_denied: true\n```\n\n### Special Caller Identifiers\n\n| Identifier | Description |\n|------|------|\n| `@external` | Top-level external call (HTTP request, CLI command, etc.) |\n| `@system` | Framework internal call |\n| `*` | Wildcard, matches all |\n\n### Conditional Rules\n\n```yaml\nrules:\n  - callers: [\"api.*\"]\n    targets: [\"executor.payment.*\"]\n    effect: allow\n    conditions:\n      identity_types: [\"user\"]      # Only user identity\n      roles: [\"admin\", \"finance\"]   # Only admin or finance roles\n      max_call_depth: 5             # Maximum call depth\n```\n\n---\n\n## Middleware\n\n\u003e Detailed definitions: [Middleware Guide](./docs/guides/middleware.md)\n\nMiddleware uses the **Onion Model**, allowing custom logic to be inserted before and after module execution:\n\n```\nRequest → [MW1.before → [MW2.before → [MW3.before →\n          [Module.execute()]\n← MW3.after] ← MW2.after] ← MW1.after] ← Response\n```\n\n```python\nclass LoggingMiddleware(Middleware):\n    def before(self, module_id: str, inputs: dict, context: Context) -\u003e dict:\n        log.info(f\"Calling {module_id} with trace_id={context.trace_id}\")\n        return inputs  # Can modify inputs\n\n    def after(self, module_id: str, inputs: dict, output: dict, context: Context) -\u003e dict:\n        log.info(f\"Result from {module_id}: success\")\n        return output  # Can modify output\n\n    def on_error(self, module_id: str, inputs: dict, error: Exception, context: Context):\n        log.error(f\"Error in {module_id}: {error}\")\n        # Return None to continue error propagation\n        # Return a dict to stop propagation and use it as recovery output\n        return None\n```\n\nTypical middleware scenarios: logging, performance monitoring, caching, rate limiting, retry, auditing.\n\n---\n\n## Configuration\n\n### Single-Package Configuration\n\nThe runtime is configured through `apcore.yaml` (legacy mode — fully backward compatible):\n\n```yaml\n# apcore.yaml\nversion: \"1.0.0\"\n\nproject:\n  name: \"my-ai-project\"\n  version: \"0.1.0\"\n\nextensions:\n  root: \"./extensions\"       # Module root directory\n  auto_discover: true        # Auto-scan and discover\n  lazy_load: true            # Lazy load (load module only on first call)\n  max_depth: 8               # Maximum directory depth\n\nschema:\n  root: \"./schemas\"\n  strategy: \"yaml_first\"     # yaml_first | native_first | yaml_only\n  validation:\n    strict: true             # Strict validation mode\n    coerce_types: true       # Automatic type coercion\n\nacl:\n  root: \"./acl\"\n  default_effect: \"deny\"     # Default deny\n  audit:\n    enabled: true\n\nlogging:\n  level: \"info\"              # trace | debug | info | warn | error | fatal\n  format: \"json\"             # json | text\n\nobservability:\n  tracing:\n    enabled: true\n    sampling_rate: 1.0       # 1.0 = full collection, 0.1 = 10% sampling\n    exporter: \"stdout\"       # stdout | otlp | jaeger\n  metrics:\n    enabled: true\n    exporter: \"prometheus\"\n```\n\n### Config Bus — Unified Ecosystem Configuration\n\nWhen using multiple apcore ecosystem packages, a single `project.yaml` can configure everything through the **Config Bus** (see [PROTOCOL_SPEC §9.4–9.14](./PROTOCOL_SPEC.md#94-config-bus-architecture)):\n\n```yaml\n# project.yaml — one file, all packages\napcore:\n  version: \"1.0.0\"\n  extensions:\n    root: ./extensions\n  project:\n    name: my-project\n\napflow:\n  api:\n    server_url: http://localhost:8000\n    timeout: 30.0\n\napcore-mcp:\n  transport: streamable-http\n  port: 8000\n\napcore-a2a:\n  name: \"My Agent\"\n  url: http://localhost:9000\n```\n\nEach package registers its own namespace with `Config.register_namespace()`. Third-party projects can also participate via `config.mount()` without modifying their existing configuration files. See the protocol spec for the full integration spectrum — from zero-coupling to full unification.\n\n**Environment variable overrides** work per namespace: `APCORE_EXECUTOR_DEFAULT__TIMEOUT=5000` for apcore, `APFLOW_API_TIMEOUT=60` for apflow, `APCORE_MCP_PORT=9000` for apcore-mcp.\n\n---\n\n## Observability\n\napcore has built-in three pillars of observability, compatible with OpenTelemetry:\n\n### Tracing\n\n- `trace_id` is automatically generated and propagated through the call chain\n- Span naming convention: `apcore.{component}.{operation}`\n- Supports export to stdout / OTLP / Jaeger\n\n### Logging\n\n- Structured logging, automatically includes `trace_id`\n- Fields marked with `x-sensitive` are automatically redacted (e.g., passwords show as `***REDACTED***`)\n- Executor automatically provides `context.redacted_inputs`, middleware and logs should use redacted data\n\n### Metrics\n\n| Metric Name | Type | Description |\n|--------|------|------|\n| `apcore_module_calls_total` | Counter | Total module calls |\n| `apcore_module_duration_seconds` | Histogram | Module execution duration distribution |\n| `apcore_module_errors_total` | Counter | Total module errors |\n\n---\n\n## Error Handling \u0026 AI Guidance\n\napcore defines a unified error format including **`ai_guidance`**. While standard errors tell a program *what* went wrong, `ai_guidance` tells the Agent **how to fix it and retry**, enabling **Self-Healing** Agents.\n\nSelf-Healing serves two higher-level goals: **Self-Repair** (autonomous error correction within a single interaction) and **Self-Evolution** (continuous system adaptation through health monitoring, feedback loops, and runtime reconfiguration).\n\n### Error Format\n\n```json\n{\n  \"code\": \"SCHEMA_VALIDATION_ERROR\",\n  \"message\": \"Input validation failed\",\n  \"details\": {\"field\": \"email\", \"reason\": \"invalid format\"},\n  \"cause\": \"ValidationError: value is not a valid email address\",\n  \"ai_guidance\": \"Please ask the user for a valid email address.\",\n  \"trace_id\": \"abc-123\",\n  \"timestamp\": \"2026-01-01T00:00:00Z\"\n}\n```\n\n### Standard Error Codes\n\n| Category | Error Code | Description | Retryable |\n|------|--------|------|--------|\n| Module | `MODULE_NOT_FOUND` | Module does not exist | No |\n| Module | `MODULE_EXECUTE_ERROR` | Execution exception | Depends |\n| Module | `MODULE_TIMEOUT` | Execution timeout | Yes |\n| Schema | `SCHEMA_VALIDATION_ERROR` | Input/output validation failed | No |\n| Schema | `SCHEMA_NOT_FOUND` | Schema file does not exist | No |\n| ACL | `ACL_DENIED` | Permission denied | No |\n| Binding | `BINDING_INVALID_TARGET` | Invalid binding target path | No |\n| Binding | `BINDING_CALLABLE_NOT_FOUND` | Bound callable object not found | No |\n| Approval | `APPROVAL_DENIED` | Approval explicitly denied | No |\n| Approval | `APPROVAL_TIMEOUT` | Approval request timed out | Yes |\n| Approval | `APPROVAL_PENDING` | Approval still pending | Yes |\n| General | `GENERAL_INTERNAL_ERROR` | Internal error | Yes |\n\n---\n\n## Cross-Language Support\n\napcore is a **language-agnostic module standard**. Canonical IDs are automatically adapted to local naming conventions in different languages:\n\n```\nCanonical ID (universal): executor.email.send_email\n\nLocal representation:\nPython:     executor/email/send_email.py      class SendEmailModule\nRust:       executor/email/send_email.rs       struct SendEmailModule\nGo:         executor/email/send_email.go       type SendEmailModule\nJava:       executor/email/SendEmail.java      class SendEmailModule\nTypeScript: executor/email/sendEmail.ts        class SendEmailModule\n```\n\n### ID Mapping Rules\n\n- Automatic language detection (based on file extension)\n- Case conversion (PascalCase ↔ snake_case ↔ camelCase)\n- Path separator normalization (`/` vs `::` vs `.`)\n- Supports manual override (`id_map` configuration)\n\n### Conformance Levels\n\nAny language SDK implementation can choose different conformance levels:\n\n| Level | Scope | Includes |\n|------|------|------|\n| **Level 0 (Core)** | Minimally viable | ID mapping, Schema loading, Registry, Executor |\n| **Level 1 (Standard)** | Production ready | + ACL, middleware, error handling, observability |\n| **Level 2 (Full)** | Complete implementation | + Extension point system, async task management, W3C Trace Context, Prometheus metrics, version negotiation, schema migration, module isolation, multi-version coexistence |\n\n**Reference Implementation**: [apcore-python](https://github.com/aiperceivable/apcore-python)\n\n---\n\n## Relationship with Other Tools\n\n### apcore vs MCP\n\n| | apcore | MCP |\n|---|--------|-----|\n| **Positioning** | Module standard | Communication protocol |\n| **Solves** | How to **build** modules | How to **call** tools |\n| **Focus** | Code organization, Schema, ACL, observability | Transport format, RPC |\n| **Relationship** | apcore modules can be exposed as MCP Server | MCP is one exposure method |\n\n### apcore vs LangChain / LlamaIndex\n\n| | apcore | LangChain etc. |\n|---|--------|-------------|\n| **Positioning** | AI-Perceivable module standard | LLM application development framework |\n| **Focus** | Module standardization, Schema, permissions | Chaining, Prompt, RAG |\n| **Relationship** | Complementary — apcore modules can serve as LangChain Tools | |\n\n### apcore vs CrewAI / AutoGen\n\n| | apcore | CrewAI etc. |\n|---|--------|----------|\n| **Positioning** | AI-Perceivable module standard | Agent orchestration framework |\n| **Focus** | Standardizing individual modules | Multi-agent collaboration strategies |\n| **Relationship** | Complementary — Agents can call apcore modules | |\n\n**In short:** apcore focuses on **building standardized, AI-understandable modules**, complementary rather than competitive with upper-layer AI protocols/frameworks.\n\n---\n\n## Implementations\n\nLanguage SDK implementations of the apcore protocol specification:\n\n| Language | Repository | Features | Install |\n|------|------|------|------|\n| **Python** | [apcore-python](https://github.com/aiperceivable/apcore-python) | Schema validation, Registry, Executor, @module decorator, YAML bindings, ACL, Middleware, Observability, Async support | `pip install apcore` |\n| **Typescript** | [apcore-typescript](https://github.com/aiperceivable/apcore-typescript) | Schema validation, Registry, Executor, @module decorator, YAML bindings, ACL, Middleware, Observability, Async support | `npm install apcore-js` |\n| **Rust** | [apcore-rust](https://github.com/aiperceivable/apcore-rust) | Schema validation, Registry, Executor, #[module] macro, YAML bindings, ACL, Middleware, Observability, Async support | `cargo add apcore` |\n\n\u003e Interested in implementing apcore for another language? See the [Protocol Specification](./PROTOCOL_SPEC.md) and [Conformance Definition](./docs/spec/conformance.md).\n\n---\n\n## Ecosystem\n\nThe apcore ecosystem uses a **core + independent adapters** architecture. The core does not include any framework-specific implementations; adapters are developed in independent repositories by official or community contributors. All packages share a unified configuration system via the **Config Bus** (§9.4).\n\n```\n                        apcore (Protocol Spec)\n                       Config Bus (§9.4–9.14)\n                               │\n          ┌────────────────────┼────────────────────┐\n          ▼                    ▼                    ▼\n   apcore-python        apcore-typescript      apcore-rust\n          │                    │                    │\n          └───────────┬────────┴───────────┬────────┘\n                      │                    │\n        ┌─────────────┼─────────────┬──────┴──────┐\n        ▼             ▼             ▼             ▼\n   apcore-mcp    apcore-a2a    apcore-cli      (others)\n  (MCP Server)  (A2A Agent)     (CLI)\n```\n\n### Official Surface Adapters\n\n| Adapter | Description | Python | TypeScript | Install |\n|---------|-------------|--------|------------|---------|\n| **[apcore-mcp](https://github.com/aiperceivable/apcore-mcp)** | Expose apcore modules as MCP Server — auto-discovery, annotation mapping, display overlay (§5.13), Tool Explorer UI | [apcore-mcp-python](https://github.com/aiperceivable/apcore-mcp-python) | [apcore-mcp-typescript](https://github.com/aiperceivable/apcore-mcp-typescript) | `pip install apcore-mcp` / `npm install apcore-mcp` |\n| **[apcore-a2a](https://github.com/aiperceivable/apcore-a2a)** | Expose apcore modules as A2A Agent — auto Agent Card, skill mapping, display overlay (§5.13), streaming, push notifications | [apcore-a2a-python](https://github.com/aiperceivable/apcore-a2a-python) | [apcore-a2a-typescript](https://github.com/aiperceivable/apcore-a2a-typescript) | `pip install apcore-a2a` / `npm install apcore-a2a` |\n| **[apcore-cli](https://github.com/aiperceivable/apcore-cli)** | Expose apcore modules as CLI commands — auto command routing from display overlay (§5.13), descriptor cache, JSON output | [apcore-cli-python](https://github.com/aiperceivable/apcore-cli-python) | [apcore-cli-typescript](https://github.com/aiperceivable/apcore-cli-typescript) | `pip install apcore-cli` / `npm install apcore-cli` |\n\n**One module definition, multiple protocol endpoints:**\n\n```python\n# Define once with apcore\n@module(id=\"email.send\", description=\"Send email\")\ndef send_email(to: str, subject: str, body: str) -\u003e dict:\n    return {\"success\": True}\n\n# Expose as MCP Server (for Claude, Cursor, etc.)\nfrom apcore_mcp import serve as mcp_serve\nmcp_serve(registry)\n\n# Expose as A2A Agent (for agent-to-agent communication)\nfrom apcore_a2a import serve as a2a_serve\na2a_serve(registry)\n\n# Expose as CLI commands (for terminal usage)\nfrom apcore_cli import serve as cli_serve\ncli_serve(registry)\n```\n\n### Developer Tooling\n\n| Project | Description | Install |\n|---------|-------------|---------|\n| **[apcore-toolkit](https://github.com/aiperceivable/apcore-toolkit)** | Shared scanner, schema extraction, display resolver, and output writers — used by framework integrations and surface adapters | `pip install apcore-toolkit` / `npm install apcore-toolkit` |\n\n### Community Adapter Types\n\n| Type | Examples | Description |\n|------|------|------|\n| **Web Frameworks** | `nestjs-apcore`, `flask-apcore`, `express-apcore` | Expose modules as HTTP APIs |\n| **AI Protocols** | `apcore-openai-tools` | Expose modules as OpenAI-compatible tools |\n| **RPC** | `apcore-grpc`, `apcore-thrift` | Expose modules as RPC services |\n\nAll adapters are built on the core's `module()` and External Binding mechanisms.\nDevelopment guide: see [Adapter Development Guide](./docs/guides/adapter-development.md).\n\n---\n\n## Documentation Index\n\n### Core Documentation\n\n| Document | Description |\n|------|------|\n| [Protocol Specification](./PROTOCOL_SPEC.md) | Complete standard specification (RFC 2119 Conformant) |\n| [Scope Definition](./SCOPE.md) | Responsibility boundaries (what's in/out of scope) |\n| [Positioning](./docs/POSITIONING.md) | Where apcore sits in the stack — relationship to MCP, A2A, CLI, REST |\n| [Roadmap](./ROADMAP.md) | Project roadmap and milestones |\n\n### Concepts \u0026 Architecture\n\n| Document | Description |\n|------|------|\n| [Core Concepts](./docs/concepts.md) | Design philosophy and core concepts explained |\n| [Architecture Design](./docs/architecture.md) | Internal architecture, component interaction, memory model |\n\n### API Reference\n\n| Document | Description |\n|------|------|\n| [APCore Client](./docs/api/client-api.md) | High-level client API (recommended entry point) |\n| [Module Interface](./docs/api/module-interface.md) | Module interface definition |\n| [Context Object](./docs/api/context-object.md) | Execution context |\n| [Registry API](./docs/api/registry-api.md) | Registry API |\n| [Executor API](./docs/api/executor-api.md) | Executor API |\n\n### Feature Specifications\n\n| Document | Description |\n|------|------|\n| [ACL System](./docs/features/acl-system.md) | Pattern-based Access Control List with first-match-wins evaluation |\n| [Core Executor](./docs/features/core-executor.md) | Central execution engine with a secured execution lifecycle |\n| [Decorator \u0026 YAML Bindings](./docs/features/decorator-bindings.md) | `@module` decorator and YAML-based module creation |\n| [Display Overlay](./PROTOCOL_SPEC.md#513-display-overlay-surface-facing-presentation) | §5.13 — sparse `display` section in binding entries for per-surface alias, description, guidance, and tags |\n| [Middleware System](./docs/features/middleware-system.md) | Composable middleware pipeline with onion execution model |\n| [Observability](./docs/features/observability.md) | Distributed tracing, metrics, and structured logging |\n| [Registry System](./docs/features/registry-system.md) | Module discovery, registration, and querying |\n| [Schema System](./docs/features/schema-system.md) | Schema loading, validation, `$ref` resolution, and export |\n| [Approval System](./docs/features/approval-system.md) | Runtime enforcement of `requires_approval` via pluggable ApprovalHandler |\n| [Event System](./docs/features/event-system.md) | Event emission, subscription, delivery lifecycle |\n| [System Modules](./docs/features/system-modules.md) | Built-in system.* modules for health, manifest, usage, control |\n\n### Usage Guides\n\n| Document | Description |\n|------|------|\n| [Creating Modules](./docs/guides/creating-modules.md) | Module creation tutorial (including four approaches) |\n| [Schema Definition](./docs/guides/schema-definition.md) | Complete Schema usage |\n| [ACL Configuration](./docs/guides/acl-configuration.md) | Access control configuration |\n| [Middleware](./docs/guides/middleware.md) | Middleware development |\n| [Adapter Development](./docs/guides/adapter-development.md) | Framework adapter development |\n| [Testing Modules](./docs/guides/testing-modules.md) | Module testing guide |\n| [Multi-Language Development](./docs/guides/multi-language.md) | Cross-language development guide |\n\n### Specification Documents\n\n| Document | Description |\n|------|------|\n| [Type Mapping](./docs/spec/type-mapping.md) | Cross-language type mapping |\n| [Conformance Definition](./docs/spec/conformance.md) | Implementation conformance levels |\n| [Algorithm Reference](./docs/spec/algorithms.md) | Core algorithm summary (including namespace, redaction, etc.) |\n\n---\n\n## Contributing\n\nContributions are welcome in the following forms:\n\n- **Specification Feedback**: Suggest improvements to the protocol specification in Issues\n- **SDK Implementation**: Implement SDKs for other languages based on [Protocol Specification](./PROTOCOL_SPEC.md)\n- **Adapter Development**: Develop adapters for web frameworks or AI protocols\n- **Documentation Improvements**: Fix, translate, or supplement documentation\n\n---\n\n## License\n\nApache 2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiperceivable%2Fapcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiperceivable%2Fapcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiperceivable%2Fapcore/lists"}