{"id":51381015,"url":"https://github.com/viggomeesters/sap-agent-context","last_synced_at":"2026-07-03T16:09:29.630Z","repository":{"id":366655734,"uuid":"1277253169","full_name":"viggomeesters/sap-agent-context","owner":"viggomeesters","description":"Source-backed SAP context bundles for AI agents, functional design, field mapping, and SAP delivery workflows.","archived":false,"fork":false,"pushed_at":"2026-06-30T06:19:36.000Z","size":1332,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T06:21:51.064Z","etag":null,"topics":["ai-agents","field-mapping","functional-design","knowledge-base","s4hana","sap"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/viggomeesters.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-22T18:14:06.000Z","updated_at":"2026-06-30T06:19:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/viggomeesters/sap-agent-context","commit_stats":null,"previous_names":["viggomeesters/sap-agent-context"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/viggomeesters/sap-agent-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viggomeesters%2Fsap-agent-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viggomeesters%2Fsap-agent-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viggomeesters%2Fsap-agent-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viggomeesters%2Fsap-agent-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viggomeesters","download_url":"https://codeload.github.com/viggomeesters/sap-agent-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viggomeesters%2Fsap-agent-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35092330,"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-07-03T02:00:05.635Z","response_time":110,"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":["ai-agents","field-mapping","functional-design","knowledge-base","s4hana","sap"],"created_at":"2026-07-03T16:09:29.115Z","updated_at":"2026-07-03T16:09:29.609Z","avatar_url":"https://github.com/viggomeesters.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SAP Agent Context\n\nSAP Agent Context is a curated, link-first context layer for AI agents working\nwith SAP functional design, field mapping, workflow, roles, scope items, and\nimplementation support. It publishes compact JSONL agent records, source\npointers, freshness metadata, bundle quality gates, and deterministic evaluation fixtures\nfor SAP S/4HANA Cloud Public Edition work.\n\nThe repository does not mirror SAP Help, SAP Notes, Learning Hub, SAP for Me, or\ncustomer content. It keeps reusable, agent-friendly metadata and cites external\nsources through access-labelled pointers.\n\n![SAP Agent Context hero](assets/hero.svg)\n\n## Highlights\n\n- Canonical JSONL agent records under `records/*.jsonl`.\n- Canonical context layout documented in\n  [Context Structure](docs/context-structure.md).\n- Rebuildable SQLite, FTS5, JSONL, and vector-ready indexes under `build/`.\n- Context bundle generation through the `sap-agent-context` CLI.\n- Completeness, evidence integrity, retrieval precision, and FO-output\n  evaluation gates.\n- Typed context bundle contract for downstream consumers such as McCoy FO\n  Generator v2 and local AI agent workflows.\n- Public/gated/internal source labels, review dates, and expiration dates to\n  prevent stale, expired, or private evidence from becoming hidden assumptions.\n\n## Installation\n\nInstall `uv` and clone the repository:\n\n```bash\ngit clone https://github.com/viggomeesters/sap-agent-context.git\ncd sap-agent-context\nuv sync\n```\n\nFor local development without a remote, use the same commands from the repository\nroot after checking out this folder.\n\n## Usage\n\nValidate the context repository:\n\n```bash\nuv run sap-agent-context validate\nuv run sap-agent-context audit-completeness\nuv run sap-agent-context evaluate-fixtures\n```\n\nSynchronize legacy authoring files into agent-first JSONL records:\n\n```bash\nuv run sap-agent-context export-jsonl --output-dir records\nuv run sap-agent-context validate-records --records-dir records\n```\n\nThe repo is JSONL-first and records-first: `records/*.jsonl` is the canonical agent record\nsurface. YAML is a legacy authoring/import format kept temporarily for bounded\nmaintainer curation; it is not the source of truth. The export writes typed JSONL files\nfor apps, tables, fields, workflows, roles, claims, sources, and relations, then\nvalidates them against `schema/*.schema.json`. The intentional\nJSONL-vault-spike alignment and compatibility deviations are documented in\n[JSONL record surface](docs/jsonl-record-surface.md). The direct-edit boundary\nfor agents is documented in\n[JSONL migration boundary](docs/jsonl-migration-boundary.md): edit bounded\nrecords or legacy packs, then validate records; do not hand-edit generated\n`build/` artifacts or bulk rewrite content to make coverage look complete.\n\nSample content claims for curation:\n\n```bash\nuv run sap-agent-context curation-report --sample-size 3 \\\n  --output build/reports/content-curation-sample.json\n```\n\nThe content curation report checks source/access, freshness, evidence and\nfail-closed wording on sampled claims, then builds a `claim_maturity_index` for\nall claims with L0/L1/L2/L3 curation readiness. It is not exhaustive SAP claim\ncertification; see [Content curation sampling](docs/content-curation-sampling.md).\n\nBuild runtime indexes:\n\n```bash\nuv run sap-agent-context build-index\nuv run sap-agent-context build-embeddings\nuv run sap-agent-context evaluate-runtime-retrieval\nuv run sap-agent-context evaluate-semantic-models\nuv run sap-agent-context runtime-search \"IE03 equipment display\" --kind sap_app --vector --limit 5\n```\n\nRuntime artifacts under `build/` are generated from canonical `records/*.jsonl`.\nSQLite + FTS5 is the primary local agent runtime; sqlite-vec is optional and\nlocal-only. DuckDB is an optional analytics/coverage companion, not the primary\nruntime store. See [Local runtime index](docs/local-runtime-index.md) and\n[Retrieval trust boundary](docs/retrieval-trust-boundary.md) for what ranked\nresults can and cannot prove.\n\nEvaluate user-style answer scenarios:\n\n```bash\nuv run sap-agent-context evaluate-answer-scenarios\n```\n\nThis is a deterministic retrieval/evidence-readiness gate. It proves that\nrepresentative questions retrieve source-labelled context, required answer terms\nand citation-bearing records. It does **not** claim live internet validation,\nexpert certification, or tenant-specific SAP truth. Fixtures may include public\nweb evidence hints for a separate human/agent review pass.\n\n| Question | Expected status | Evidence-readiness result |\n|---|---:|---|\n| `Technical fields in MARA?` | `ready` | retrieves the MARA DD03VT field-catalog anchor and requires `MARA.MATNR`, `MARA.MTART`, `DD03VT` on that record |\n| `Field description voor MTART` / `MTART omschrijving` | `ready` | retrieves the MARA field catalog and requires `MARA.MTART`, `Material Type`, `Artikelsoort` |\n| `In welke tabellen kan ik het veld MATNR vinden?` / `Welke tabellen hebben MATNR?` | `ready` | retrieves MARA and EQUI field-catalog anchors and requires `MARA.MATNR` plus `EQUI.MATNR` |\n| `Hoe zit het precies met organisaties scheiden in SAP?` / `Hoe scheid je organisatie-eenheden in SAP?` | `ready` | retrieves org/process lenses for company code, plant, purchasing organization and sales organization with fail-closed evidence boundaries |\n| `Wat is purchase to pay?` / `Wat is procure to pay?` | `ready` | retrieves the P2P/process lens and purchasing-organization context |\n| `Welke SAP modules zijn er?` | `needs_curation` | retrieves foundation/context lenses, but deliberately refuses to claim an exhaustive module taxonomy from current records |\n\nExample report fragment:\n\n```json\n{\n  \"artifact_kind\": \"answer_scenario_evaluation_report\",\n  \"status\": \"passed\",\n  \"fixtures\": 11,\n  \"contract\": {\n    \"live_web_boundary\": \"Fixtures can carry external evidence hints, but this deterministic gate does not claim live internet validation or expert certification.\",\n    \"answer_boundary\": \"Retrieved context is answer evidence, not tenant/client-specific SAP configuration proof.\"\n  }\n}\n```\n\nExample scenario result:\n\n```json\n{\n  \"id\": \"concrete_mtart_description_paraphrase_nl\",\n  \"question\": \"MTART omschrijving\",\n  \"expected_answer_status\": \"ready\",\n  \"status\": \"passed\",\n  \"top_ids\": [\n    \"sap.field-set.ecc-anonymous-mara-dd03vt-field-catalog\"\n  ],\n  \"external_evidence_hints\": {\n    \"mode\": \"offline_hint\",\n    \"accepted_domains\": [\"sapdatasheet.org\", \"se80.co.uk\", \"sap.com\"],\n    \"search_terms\": [\"SAP MTART description Material Type\", \"SAP field MTART Artikelsoort\"]\n  }\n}\n```\n\nGenerate deterministic consultant-style prose from the same local evidence:\n\n```bash\nuv run sap-agent-context consultant-answer \"Hoe scheid je organisatie-eenheden in SAP?\"\nuv run sap-agent-context evaluate-consultant-answers\n```\n\nThis layer produces a compact answer plus citations and explicit boundaries. It is a narrow deterministic/extractive scenario layer: no LLM call, no live-web certification, no tenant-specific truth claim, and unsupported/generic questions return `needs_curation` instead of `ready`.\n\nExample answer fragment:\n\n```json\n{\n  \"artifact_kind\": \"sap_consultant_answer\",\n  \"status\": \"ready\",\n  \"question\": \"Hoe scheid je organisatie-eenheden in SAP?\",\n  \"answer\": \"In SAP, organizational separation should be explained through multiple lenses rather than one magic hierarchy: company code, plant, purchasing organization and sales organization can separate legal, logistics, buying and sales responsibilities...\",\n  \"citations\": [\n    {\n      \"id\": \"sap.field-set.sap-process-lenses\",\n      \"kind\": \"sap_field\",\n      \"source_ids\": [\"sap.source.sap-field-set-sap-process-lenses\"],\n      \"claim_ids\": [\"sap.claim.sap-field-set-sap-process-lenses.001\"]\n    }\n  ],\n  \"boundary\": {\n    \"live_web_validation\": false,\n    \"expert_certification\": false,\n    \"tenant_specific_truth\": false\n  }\n}\n```\n\nGenerate a context bundle:\n\n```bash\nuv run sap-agent-context query \\\n  --intent fo.workflow \\\n  --topic \"supplier-invoice workflow\" \\\n  --sap-product s4hana_cloud_public \\\n  --limit 12 \\\n  --output build/context-bundles/supplier-invoice-workflow.json\n```\n\nCreate a McCoy local-folder provider manifest:\n\n```bash\nuv run sap-agent-context mccoy-provider \\\n  build/context-bundles/supplier-invoice-workflow.json \\\n  --title \"SAP Agent Context bundle - supplier-invoice workflow\" \\\n  --output build/context-bundles/mccoy-provider.json\n```\n\n## Agent Setup\n\nFor local AI workflows, each colleague can clone the repository and register the\ngenerated bundle directory with their agent or source-provider layer:\n\n```bash\ngit clone https://github.com/viggomeesters/sap-agent-context.git sap-agent-context\ncd sap-agent-context\nuv sync\nuv run sap-agent-context query \\\n  --intent fo.workflow \\\n  --topic \"supplier-invoice workflow\" \\\n  --sap-product s4hana_cloud_public \\\n  --limit 12 \\\n  --output build/context-bundles/supplier-invoice-workflow.json\n```\n\nThe generated bundle includes `producer.name: sap-agent-context` and\n`producer.contract: sap-agent-context-bundle`. The legacy\n`bundle_kind: sap_fo_context_bundle` remains for backward-compatible consumers.\n\nRepresentative no-gap queries:\n\n```bash\nuv run sap-agent-context query --intent fo.workflow --topic \"supplier-invoice workflow\" --sap-product s4hana_cloud_public --limit 12\nuv run sap-agent-context query --intent fo.sap_configuration --topic \"procurement purchase requisition workflow\" --sap-product s4hana_cloud_public --limit 12\nuv run sap-agent-context query --intent fo.field_mapping --topic \"business partner master data\" --sap-product s4hana_cloud_public --limit 12\nuv run sap-agent-context query --intent fo.test_scenarios --topic \"sales order output management\" --sap-product s4hana_cloud_public --limit 12\nuv run sap-agent-context query --intent fo.authorization --topic \"integration communication role authorization api\" --sap-product s4hana_cloud_public --limit 12\n```\n\n## Completeness Scope\n\nThe current product-grade scope is `sap_fo_starter_coverage`, defined in\n`schema/completeness-matrix.yaml`.\n\nIt covers starter Functional Design knowledge for finance/AP, procurement,\nsales, master data, migration, workflow, output management, authorizations,\nintegrations, extensibility, and analytics/reporting. The scope is intentionally\nbounded: it is not exhaustive SAP product coverage. It is complete when\n`sap-agent-context audit-completeness` reports zero critical and zero important\ngaps.\n\nRepresentative bundles are also checked against the\n[Bundle Quality Contract](docs/bundle-quality-contract.md), so completeness is\nnot only item-count and knowledge-kind coverage.\n\nFor repeatable domain-density work, use the\n[Deep domain pack template](docs/deep-domain-pack-template.md) and\n`examples/deep-domain-pack-template.yaml`. The template is derived from the\ncompleted EAM/PM lifecycle slice and defines the required source references, FO\npatterns, decision rules, tests, fixtures, and bounded thresholds for a named\nslice without claiming exhaustive SAP coverage.\n\nThe product and design contract is captured in the\n[Vision and design principles](docs/vision.json): a cloneable, local-first SAP context runtime for agents that is self-contained, fast, compact, reliable, source-labelled, JSON-first and fail-closed.\n\n## Development\n\nRun the full local quality gate:\n\n```bash\nmake check\nmake audit-v02-gap-report\n```\n\n`make check` expands to:\n\n```bash\nuv run sap-agent-context validate\nuv run sap-agent-context audit-completeness\nuv run sap-agent-context evaluate-fixtures\nuv run sap-agent-context build-index\nuv run sap-agent-context build-embeddings\nuv run sap-agent-context evaluate-runtime-retrieval\nuv run sap-agent-context evaluate-semantic-models\nuv run pytest -q\nuv run ruff check .\ngit diff --check\n```\n\n`make audit-v02-gap-report` is fail-hard; it must fail the command when the\nv0.2 coverage matrix reports blocking findings.\n\nThe CI workflow runs `make check` and `make audit-v02-gap-report` on pushes and\npull requests.\n\n## McCoy Integration\n\n`mccoy-fo-generator-v2` can register generated bundle directories as local\nsource providers:\n\n```bash\ncd /path/to/mccoy-fo-generator-v2\nuv run fo-gen-v2 register-source \u003cworkspace\u003e \u003cproject-id\u003e \\\n  --type local-folder \\\n  --title \"SAP Agent Context bundle - supplier-invoice workflow\" \\\n  --path \"/path/to/sap-agent-context/build/context-bundles\" \\\n  --provenance sap-agent-context\n```\n\nTyped consumers should use the\n[Agent Consumer Contract](docs/agent-consumer-contract.md). McCoy-specific\nlocal-folder registration remains an example integration path in\n[McCoy FO Generator v2 Hook Contract](docs/mccoy-fo-generator-v2-hook.md).\n\n## Privacy And Security\n\nThis repository is designed for public release. It stores generic SAP context,\nFunctional Design patterns, field mapping context, and source pointers, not\ncustomer-specific evidence. Do not add tenant exports, client screenshots, SAP\nNotes content, credentials, `.env` files, private keys, personal data, or\nproprietary customer material.\n\nThe `supplier-invoice` filenames are generic SAP process examples, not customer\nor private invoice records. See `docs/public-readiness.md` for the current\npublication checklist and privacy review notes.\n\nReport security issues privately according to [SECURITY.md](SECURITY.md).\n\n## Release\n\nThis Python package is source-first. Public releases should be created as GitHub\ntags/releases after the quality gate passes.\n\n## Remote Strategy\n\nCanonical public repository:\n\n```text\nhttps://github.com/viggomeesters/sap-agent-context\n```\n\nRecommended GitHub metadata:\n\n- Description: `Source-backed SAP context bundles for AI agents, functional design, and field mapping.`\n- Topics: `sap`, `s4hana`, `ai-agents`, `functional-design`, `field-mapping`, `knowledge-base`\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\n\n## SAP GUI EAM/PM examples\n\n- [SAP GUI EAM/PM clone-first queries](examples/sap-gui-eam-pm-queries.json)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviggomeesters%2Fsap-agent-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviggomeesters%2Fsap-agent-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviggomeesters%2Fsap-agent-context/lists"}