{"id":51129612,"url":"https://github.com/robkatzenberger/apex-lite","last_synced_at":"2026-06-25T11:01:02.451Z","repository":{"id":347112223,"uuid":"1109898029","full_name":"robkatzenberger/APEX-Lite","owner":"robkatzenberger","description":"APEX (Action Policy EXecution) is a minimal, external execution boundary for AI systems. It evaluates declared agent intent against explicit, operator-defined policy before execution, enabling deterministic, inspectable control without relying on in-model guardrails.","archived":false,"fork":false,"pushed_at":"2026-03-26T19:13:24.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T07:23:13.748Z","etag":null,"topics":["agentic-ai","agentic-framework","ai","ai-governance","ai-policy","ai-policy-layer","ai-pre-execution","ai-safety","developer-tools","execution-boundry","infrastructure","policy-engine","safety-critical-systems","safety-monitoring","security-tools","trusted-execution-environment","trustworthy-ai"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/robkatzenberger.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-04T12:42:40.000Z","updated_at":"2026-03-26T19:13:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/robkatzenberger/APEX-Lite","commit_stats":null,"previous_names":["robkatzenberger/apex-lite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/robkatzenberger/APEX-Lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkatzenberger%2FAPEX-Lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkatzenberger%2FAPEX-Lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkatzenberger%2FAPEX-Lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkatzenberger%2FAPEX-Lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robkatzenberger","download_url":"https://codeload.github.com/robkatzenberger/APEX-Lite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robkatzenberger%2FAPEX-Lite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34771664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic-ai","agentic-framework","ai","ai-governance","ai-policy","ai-policy-layer","ai-pre-execution","ai-safety","developer-tools","execution-boundry","infrastructure","policy-engine","safety-critical-systems","safety-monitoring","security-tools","trusted-execution-environment","trustworthy-ai"],"created_at":"2026-06-25T11:01:00.764Z","updated_at":"2026-06-25T11:01:02.434Z","avatar_url":"https://github.com/robkatzenberger.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# APEX-Lite\n\nAPEX-Lite is a minimal external pre-execution policy boundary for AI systems.\n\nAPEX-Lite evaluates declared intent before execution. It compares that intent to explicit operator-defined policy, returns a deterministic decision, emits a receipt, and can append that receipt to an audit log.\n\nThis repository is the minimal public reference implementation of APEX-Lite. It is meant to be understandable, inspectable, and broadly reusable on its own. It does not claim to include every private, enterprise, or patent-backed implementation detail that may exist around the broader APEX approach.\n\nThe open-source reference implementation now also includes a local gate configuration under `config/`. That file defines the required request fields and simple keyword-driven gates such as email and folders.\nIt also includes an optional local notification configuration under `config/` for SMS escalation notices.\n\n## What APEX-Lite Does\n\nAPEX-Lite is:\n\n- a narrow pre-execution policy evaluator\n- a deterministic decision engine\n- an external pre-execution policy boundary\n- a local reference implementation built for inspection and replay\n\nThe current reference flow is:\n\n1. Read an intent JSON file.\n2. Read a local policy file in the repository's simple YAML-like format.\n3. Evaluate the intent against policy rules in order.\n4. Return `ALLOW` or `REQUIRE_APPROVAL`.\n5. Emit a structured JSON receipt.\n6. Optionally append the receipt to a JSONL audit log.\n\n## What APEX-Lite Does Not Do\n\nAPEX-Lite is not:\n\n- an AI agent\n- an orchestration framework\n- a monitoring platform\n- an in-model safety layer\n\nIt does not rely on LLM reasoning for policy outcomes.\n\n## Decision Model\n\nThe decision model is intentionally small:\n\n- `ALLOW`\n- `REQUIRE_APPROVAL`\n\nNormal uncertainty routes to approval rather than hard denial. The current implementation keeps the existing `REQUIRE_APPROVAL` label so it can later map cleanly to `ESCALATE`.\n\nEscalation is treated as a positive transparency signal, not a failure state. The reference implementation does not expose a normal `DENY` or block path. It operates in `ALLOW_OR_ESCALATE` mode and records escalations with a reward signal rather than punishing honest declaration.\nIf both a gate and a YAML rule apply, `REQUIRE_APPROVAL` wins over `ALLOW`.\n\n## Policy Format\n\nAPEX-Lite reads the repository's existing rule format.\n\n```yaml\nrules:\n  - id: rule_01\n    description: Require approval for high-risk actions\n    if: risk == \"high\"\n    require: human_approval\n\n  - id: rule_02\n    description: Require approval when PII is involved\n    if: action == \"send_email\" and \"PII\" in data_classes\n    require: human_approval\n```\n\nThe evaluator intentionally supports only a small, explicit expression set used by this repo:\n\n- equality checks like `risk == \"high\"`\n- inequality checks like `risk != \"low\"`\n- array membership like `\"PII\" in data_classes`\n- `and` / `or` combinations\n\n## CLI\n\nRun an evaluation:\n\n```bash\nnode bin/apex-lite.js evaluate examples/intent.json examples/policy.yaml\n```\n\nAppend the receipt to an audit log:\n\n```bash\nnode bin/apex-lite.js evaluate examples/intent.json examples/policy.yaml --log var/audit.jsonl\n```\n\nThe CLI prints the receipt JSON to stdout and exits nonzero on invalid usage or parse errors.\n\n## Operator Console\n\nAPEX-Lite also includes a small local execution console built as a thin UI over the real engine.\n\nStart it with:\n\n```bash\nnpm start\n```\n\nThen open [http://localhost:3000](http://localhost:3000).\n\nThe console:\n\n- accepts manual intent input\n- accepts a local operator identifier for escalation outcomes\n- accepts `declared_intent`, request `version`, and `log_id`\n- posts to `POST /api/evaluate`\n- posts queue approvals and escalations to `POST /api/operator-action`\n- displays the real receipt returned by the engine\n- appends real evaluation results to the feed\n- routes `REQUIRE_APPROVAL` decisions into a local escalation queue\n- fetches recent receipts from `GET /api/audit`\n\nThe local server uses:\n\n- the example policy under `examples/`\n- the append-only audit log under `var/`\n- the optional notification configuration under `config/`\n\nThe console also makes the trust model explicit to the submitting party: the declared intent is entering a policy gate, and gaming that declaration is not beneficial for either side because it breaks trust in the boundary itself.\n\n## Receipt\n\nA receipt is the deterministic record produced for one policy evaluation. It includes:\n\n- `receipt_type`\n- `apex_version`\n- `evaluated_at`\n- `receipt_id`\n- `control_mode`\n- `blocking`\n- `decision`\n- `reason`\n- `policy_id`\n- `reward_signal`\n- `original_intent`\n\nExample:\n\n```json\n{\n  \"receipt_type\": \"apex-lite.receipt\",\n  \"apex_version\": \"0.1.0\",\n  \"evaluated_at\": \"2026-01-01T00:00:00.000Z\",\n  \"receipt_id\": \"rcpt_INT_001_20260101T000000000Z\",\n  \"control_mode\": \"ALLOW_OR_ESCALATE\",\n  \"blocking\": false,\n  \"decision\": \"REQUIRE_APPROVAL\",\n  \"reason\": \"Email gate matched escalation keywords\",\n  \"policy_id\": \"email_gate\",\n  \"reward_signal\": \"TRANSPARENCY_REWARDED\",\n  \"original_intent\": {\n    \"intent_id\": \"INT-001\",\n    \"actor\": \"agent_42\",\n    \"declared_intent\": \"send external customer email with pii attachment\",\n    \"action\": \"send_email\",\n    \"target\": \"external_user\",\n    \"risk\": \"medium\",\n    \"intent_version\": \"1\",\n    \"log_id\": \"LOG-001\",\n    \"data_classes\": [\"PII\"],\n    \"timestamp\": 1730000000\n  }\n}\n```\n\n`receipt_id` is a plain readable identifier for the local reference build. It gives operators and audit entries a simple way to refer to one evaluation. \n\n## Gate Config\n\nThe local gate configuration lives under `config/`.\n\nIt gives the open-source build one plain place to define:\n\n- required request fields such as user or agent name, date and time, declared intent, version number, and log id\n- gate categories such as email and folders\n- keywords that should escalate\n- keywords that are safe to allow\n\nGate matching is intentionally simple and deterministic. It uses normalized whole-keyword matching rather than arbitrary substring matching, and YAML policy rules still run after gate evaluation so approval requirements cannot be bypassed by a gate allow match.\n\n## Audit Log\n\nThe optional audit log is append-only JSONL. Each evaluation appends one receipt as one line.\nEscalation resolutions also append operator action entries with an explicit `outcome`, so the audit trail records not just that escalation occurred, but how it ended.\nThose action entries also record the resolving operator identifier.\nEscalation notifications can also append `apex-lite.notification` entries so operators can see whether an SMS notice was skipped, simulated, sent, or failed.\nOnly one operator outcome is accepted for a given escalated receipt.\nOperator-action verification reads the audit log once per request and checks the referenced `receipt_id` and prior operator outcome against that recorded history.\n\nThat keeps the first implementation:\n\n- simple\n- local\n- inspectable\n- easy to replay with standard tooling\n\n## Tests\n\nRun the test suite with:\n\n```bash\nnpm test\n```\n\nThe tests cover:\n\n- high-risk escalation\n- PII escalation\n- safe allow behavior\n- YAML approval rules overriding gate allow matches\n- whole-keyword gate matching instead of arbitrary substring matches\n- plain receipt id presence\n- one-line-per-evaluation audit logging\n- real `POST /api/evaluate` responses\n- real `POST /api/operator-action` responses\n- real `GET /api/audit` responses\n- rejection of forged or non-escalated operator actions\n\n## Repository Shape\n\nThe current implementation is intentionally small:\n\n- `bin/apex-lite.js`\n- `src/engine`\n- `src/policy`\n- `src/receipt`\n- `src/audit`\n- `src/index`\n- `src/server`\n- `src/operator-action`\n- `src/gates`\n- `src/notifications`\n- `config/`\n- `public/`\n\nThis is meant to feel closer to a SCADA-style interlock or admission controller than to an autonomous system.\n\n## License\n\nThis repository is licensed under Apache-2.0. See `LICENSE`.\n\nThat permissive license applies to this public reference implementation. It should not be read as a claim that every enterprise deployment pattern, private implementation detail, or broader patent-backed system around APEX-Lite is included in this repository.\nCopyright 2025 Robert Katzenberger\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobkatzenberger%2Fapex-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobkatzenberger%2Fapex-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobkatzenberger%2Fapex-lite/lists"}