{"id":46102169,"url":"https://github.com/manasaranjanbehera/llm-structural-gate","last_synced_at":"2026-03-01T20:01:24.094Z","repository":{"id":341364560,"uuid":"1169250608","full_name":"manasaranjanbehera/llm-structural-gate","owner":"manasaranjanbehera","description":"Deterministic structural validation service enforcing strict JSON schema contracts.","archived":false,"fork":false,"pushed_at":"2026-03-01T10:51:48.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T14:22:08.489Z","etag":null,"topics":["ai-governance","deterministic","fastapi","json","llm","pydantic","schema-validation"],"latest_commit_sha":null,"homepage":"","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/manasaranjanbehera.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":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":"2026-02-28T11:58:41.000Z","updated_at":"2026-03-01T10:49:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/manasaranjanbehera/llm-structural-gate","commit_stats":null,"previous_names":["manasaranjanbehera/llm-structural-gate"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/manasaranjanbehera/llm-structural-gate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manasaranjanbehera%2Fllm-structural-gate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manasaranjanbehera%2Fllm-structural-gate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manasaranjanbehera%2Fllm-structural-gate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manasaranjanbehera%2Fllm-structural-gate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manasaranjanbehera","download_url":"https://codeload.github.com/manasaranjanbehera/llm-structural-gate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manasaranjanbehera%2Fllm-structural-gate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29983122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T16:35:47.903Z","status":"ssl_error","status_checked_at":"2026-03-01T16:35:44.899Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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-governance","deterministic","fastapi","json","llm","pydantic","schema-validation"],"created_at":"2026-03-01T20:01:23.207Z","updated_at":"2026-03-01T20:01:24.066Z","avatar_url":"https://github.com/manasaranjanbehera.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# llm-structural-gate\n\n![CI](https://github.com/manasaranjanbehera/llm-structural-gate/actions/workflows/ci.yml/badge.svg)\n\nA minimal prototype that implements a **Structural Constraint Gate** for LLM outputs: a deterministic contract boundary between probabilistic generation and downstream application logic.\n\n---\n\n## Problem Statement\n\nLLM outputs are probabilistic. Tokens are sampled; formatting and structure vary. Downstream systems often assume a fixed contract (e.g. JSON with required fields and types). Using raw LLM output as if it were a deterministic API response leads to parse failures, type errors, and undefined behavior.\n\nA **Structural Constraint Gate** is a validation layer that accepts or rejects output strictly against a schema. Only well-formed, schema-compliant data crosses the boundary. Rejected output does not reach the rest of the system.\n\nThis is **structural validation**, not semantic safety filtering. The gate checks shape, types, required fields, and allowed values. It does not evaluate truthfulness, intent, or business rules. A structurally valid response can still be wrong or misleading.\n\n---\n\n## What This Project Does\n\n- Validates raw LLM output (here, simulated as JSON strings) against a single fixed schema.\n- Enforces **strict** structural rules: no type coercion (e.g. string or int to float is rejected), exact enum matching (case-sensitive), no extra fields.\n- Returns either the validated structured object (accept) or a rejection with reason (reject). No silent correction, retries, or auto-fix.\n- This project intentionally avoids semantic judgment, business rule validation, or auto-correction. It enforces structure only.\n\n\nThe prototype uses a simulated LLM client (no external API). The validation path is local and deterministic.\n\n---\n\n## How It Works\n\n1. Raw output (e.g. from an LLM) is passed as a string.\n2. The string is parsed as JSON. Parse failure → reject.\n3. The parsed object is validated against the schema. Validation failure → reject.\n4. Success yields a typed instance; failure yields an error reason.\n\nCore API: `validate(raw_output: str) → ValidationSuccess | ValidationFailure`.\n\n---\n\n## Architecture Overview\n\n```\n    User Input\n         │\n         ▼\n   Prompt Builder\n         │\n         ▼\n        LLM\n         │\n         ▼\n   ┌─────────────────────────────────────────┐\n   │  Structural Gate                        │\n   │  (Deterministic Contract Boundary)      │\n   │  Schema Validation Layer                │\n   └─────────────────────────────────────────┘\n         │\n         ▼\n   Accept / Reject\n         │\n         ▼\n   Downstream System\n```\n\nThe Structural Gate is the single place where output is checked against the contract. Nothing that fails validation reaches the downstream system.\n\n---\n\n## Structural Constraint Examples\n\n### Schema (fixed in this prototype)\n\n**SentimentResult** — all fields required, no extra properties:\n\n| Field       | Type  | Constraint                                      |\n|------------|-------|--------------------------------------------------|\n| sentiment  | enum  | `\"positive\"` \\| `\"negative\"` \\| `\"neutral\"`      |\n| confidence | float | 0.0 ≤ value ≤ 1.0 (strict float; no int/string)  |\n| summary    | string| minLength 5                                     |\n\n### Example: passes validation\n\n```json\n{\"sentiment\": \"positive\", \"confidence\": 0.92, \"summary\": \"Customer is happy\"}\n```\n\n### Example: fails validation\n\n- Malformed JSON: `{\"sentiment\": \"positive\" \"confidence\": 0.92, ...}` → reject (parse error).\n- Wrong type: `\"confidence\": \"0.92\"` (string) or `\"confidence\": 1` (int) → reject (strict float).\n- Enum: `\"sentiment\": \"Positive\"` or `\"positve\"` → reject (exact enum only).\n- Extra field: `\"reasoning\": \"...\"` → reject (additional properties forbidden).\n- Missing field: no `summary` → reject.\n\n### Python usage\n\n```python\nfrom app.validator import validate\n\nraw = '{\"sentiment\": \"positive\", \"confidence\": 0.92, \"summary\": \"Customer is happy\"}'\nresult = validate(raw)\n\nif hasattr(result, \"instance\"):\n    # Accepted: use result.instance (typed SentimentResult)\n    print(result.instance.model_dump())\nelse:\n    # Rejected: result.reason describes the failure\n    print(\"Rejected:\", result.reason)\n```\n\n---\n\n## Example Usage\n\n### Run the API\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate   # Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn app.main:app --reload\n```\n\nServer: `http://127.0.0.1:8000`\n\n### Invoke (simulator modes)\n\n**POST /invoke** body: `{\"mode\": \"VALID\"}`.\n\nModes include: `VALID`, `ENUM_VIOLATION`, `EXTRA_FIELD`, `MISSING_FIELD`, `NUMERIC_BOUND_VIOLATION`, `MALFORMED_JSON`, `STRING_INSTEAD_OF_FLOAT`, `INT_INSTEAD_OF_FLOAT`, `ENUM_CASE_VARIATION`, `SEMANTICALLY_WRONG`. Any other `mode` returns 400 (unknown mode).\n\n- **Validation passes:** 200 with the validated JSON.\n- **Validation fails:** 400 with `{\"status\": \"rejected\", \"reason\": \"\u003cmessage\u003e\"}`.\n\n```bash\n# Accepted\ncurl -s -X POST http://127.0.0.1:8000/invoke -H \"Content-Type: application/json\" -d '{\"mode\": \"VALID\"}'\n\n# Rejected (e.g. enum typo)\ncurl -s -X POST http://127.0.0.1:8000/invoke -H \"Content-Type: application/json\" -d '{\"mode\": \"ENUM_VIOLATION\"}'\n```\n\n---\n\n## Tests\n\n```bash\npip install -r requirements.txt\npytest tests/ -v\n```\n\n---\n\n## Roadmap\n\nThis prototype focuses exclusively on structural validation.\nFuture exploration may include:\n\n- Multi-schema support (contract per workflow).\n- Structured output prompting integration.\n- Typed client SDK generation from schema.\n- Integration with execution workflows (e.g., reject → retry policy at application layer).\n\nThe gate itself will remain a deterministic boundary. Retry logic, fallback policy, and business rules belong outside this layer.\n\n---\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests, and pull request guidelines. Security issues: see [SECURITY.md](SECURITY.md); do not report them as public issues.\n\n---\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanasaranjanbehera%2Fllm-structural-gate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanasaranjanbehera%2Fllm-structural-gate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanasaranjanbehera%2Fllm-structural-gate/lists"}