{"id":51393980,"url":"https://github.com/akshiin/andersen-trial-task","last_synced_at":"2026-07-04T01:34:23.118Z","repository":{"id":365068298,"uuid":"1267073322","full_name":"akshiin/andersen-trial-task","owner":"akshiin","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-15T17:37:35.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T01:34:19.552Z","etag":null,"topics":["automation","pydantic","python","rule-based-system"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akshiin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2026-06-12T07:38:53.000Z","updated_at":"2026-06-15T17:37:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akshiin/andersen-trial-task","commit_stats":null,"previous_names":["akshiin/andersen-trial-task"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akshiin/andersen-trial-task","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshiin%2Fandersen-trial-task","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshiin%2Fandersen-trial-task/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshiin%2Fandersen-trial-task/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshiin%2Fandersen-trial-task/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akshiin","download_url":"https://codeload.github.com/akshiin/andersen-trial-task/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akshiin%2Fandersen-trial-task/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35107463,"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":["automation","pydantic","python","rule-based-system"],"created_at":"2026-07-04T01:34:22.640Z","updated_at":"2026-07-04T01:34:23.113Z","avatar_url":"https://github.com/akshiin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SecureHealth Adjudication Engine\n\n## Conceptual Approach \u0026 Architecture\n\n### 1. Rules-as-Data Architecture\n\nPolicy parameters (like a 10% coinsurance rate or an AED 50 deductible) are not written directly into the code logic. Instead, this engine stores all policy settings as structured, read-only data objects using **Pydantic v2**. The calculation functions never depend on specific values. To change an endorsement or switch to a different plan, you just create a new data object — the math code stays the same and works for any member.\n\n### 2. Hybrid Automation Strategy\n\nThis engine is built to scale in the real world using a **Hybrid Architecture**:\n\n* **The Input Layer (Deterministic Schemas):** Raw data from medical bills or invoices is read and checked against strict typed `Claim` schemas. This removes errors from manual input or AI-generated guesses on important fields like service dates and network types.\n\n* **The Processing Core (Deterministic Python Logic):** All financial calculations follow a fixed, step-by-step pipeline that matches the policy's **GC-1 Order of Calculation** (Base Eligibility $\\rightarrow$ Deductible Subtraction $\\rightarrow$ Coinsurance Splits $\\rightarrow$ Dynamic Limit Checks).\n\n* **The Output Layer (User Explanation Generation):** The engine produces a structured JSON settlement record with `rule_justifications` generated directly by the code. This output is easy to pass into an LLM to create plain-language letters or explanation dashboards for customers.\n\n---\n\n## Why Naive Vector-Search/RAG Approaches Fail on This Task\n\nA standard vector-search (RAG) or LLM-agent approach is too unreliable for health-insurance claim adjudication and will not produce the accurate audit trails this work requires. Here is why:\n\n1. **Context Window Fragmentation \u0026 Shadow Overrides:** RAG splits documents into chunks. If the engine picks up a base benefit limit (e.g., the Physiotherapy cap) from one chunk, it will likely miss an Endorsement clause in a different chunk that changes that value.\n\n\n2. **Lack of Chronological State Awareness:** Policy limits and annual caps decrease over time as claims are processed. LLMs have no built-in mechanism to track running totals and balances across multiple separate claim calculations.\n\n\n3. **Mathematical Instability:** LLMs are text prediction models, not calculators. They often produce wrong numbers or fail entirely when asked to perform chained operations like deductible subtractions, coinsurance splits, and sliding-scale cap checks in sequence.\n\n---\n\n## Project Structure Overview\n\nAll shared engine logic lives in the `securehealth/` package, split into three layers: **Models $\\rightarrow$ Services $\\rightarrow$ Data**. The top-level scripts use this package to run each question and print results.\n\n```\nandersen-trial-task/\n├── pyproject.toml         # Project metadata, dependencies, and Hatchling build backend\n├── uv.lock                # Locked dependency versions for absolute build reproducibility\n├── .python-version        # Pins environment execution to Python 3.11\n├── .gitignore             # Standard Python and uv environment git ignores\n├── README.md              # Project documentation and architectural overview\n├── q1.py                  # Entry point: Endorsement resolution (Question 1)\n├── q2.py                  # Entry point: Annual aggregate limit setup (Question 2)\n├── q3.py                  # Entry point: Single-claim settlement calculation (Question 3)\n├── q4.py                  # Entry point: Batch adjudication + policy exclusions (Question 4)\n├── q5.py                  # Entry point: Stateful sequential adjudication engine (Question 5)\n├── q6.py                  # Entry point: Structured settlement statement — JSON + CSV output (Question 6)\n└── securehealth/          # Shared core domain package\n    ├── __init__.py        # Re-exports public services and domain types\n    ├── models/            # Pydantic domain models (Split by concept, not by question)\n    │   ├── __init__.py    # Central entry point for core models\n    │   ├── enums.py       # Type-safe enums (e.g., NetworkType)\n    │   ├── benefit.py     # BenefitTerms schema (caps, sub-limits, network cover rules)\n    │   ├── policy.py      # PolicyConfig schema (limits, endorsement appliers, ledger state)\n    │   └── claim.py       # Claim schema (billed amounts, flags, notes, dates)\n    ├── services/          # Business logic and financial calculation pipelines\n    │   ├── __init__.py    # Central entry point for service classes and functions\n    │   ├── endorsement.py # Endorsement E1 parameter transformation logic\n    │   ├── settlement.py  # Core GC-1 calculation pipeline implementation\n    │   ├── adjudication.py# Policy exclusion and penalty evaluation filters\n    │   └── stateful_adjudication.py # Stateful adjudication engine + settlement statement builder\n    └── data/              # Centralized testing data and policy fixtures\n        ├── __init__.py    # Central entry point for centralized data\n        └── fixtures.py    # Policy rules, Endorsement E1, and Claims C1–C6 datasets\n\n```\n\n---\n\n## Entry Point Mapping \u0026 Execution\n\nThe top-level scripts (`q1.py` through `q6.py`) are simple runners. They load the fixture data, pass it through the right service functions, and print the results (JSON output for questions 3 to 5; file output for question 6).\n\n| Script | Question Target | Internal Modules Called | Primary Objective |\n| --- | --- | --- | --- |\n| `q1.py` | Endorsement Resolution | `endorsement.resolve_q1_terms` | Shows the Physiotherapy sub-limit and coinsurance values before and after Endorsement E1 is applied.\n| `q2.py` | Aggregate Initialisation | `models.policy.PolicyConfig` | Creates a fresh policy config and prints the base aggregate limit (AED 250,000).\n| `q3.py` | Single-Claim Settlement | `settlement.calculate_single_claim` | Runs Claim **C1** through the GC-1 calculation steps and shows the deductible and 10% coinsurance split.\n| `q4.py` | Batch Exclusions | `adjudication.process_all_claims` | Processes all claims (C1–C6) one by one, marking which ones are not payable using the chronic condition filter (Exclusion 4.2) and late-submission penalty (GC-3).\n| `q5.py` | Stateful Adjudication | `stateful_adjudication.StatefulAdjudicationEngine` | Runs all six claims in order, updating sub-limits and the aggregate balance after each claim.\n| `q6.py` | Settlement Statement | `stateful_adjudication.build_settlement_statement` | Builds a full settlement report per claim (billed, eligible, deductible, coinsurance, insurer-paid, member-paid, decision/reason) with year-end totals, saved to `settlement_statement.json` and `settlement_statement.csv`.\n\n### Running the Engine Locally\n\nThis project uses `uv` for fast and reliable dependency management. Run the steps below to set up your environment and execute any question script:\n\n```bash\n# Clone the repository and navigate to the project root\ncd andersen-trial-task\n\n# Synchronize virtual environment dependencies and lock state\nuv sync\n\n# Run specific question scripts to inspect formatted ledger console printouts\nuv run python q1.py\nuv run python q3.py\nuv run python q5.py\n\n# Run q6 to generate settlement_statement.json and settlement_statement.csv\nuv run python q6.py\n\n```\n\n---\n\n## Layered Architecture Pattern\n\nEach layer only depends on the layer below it, keeping the code clean and easy to change:\n\n```\n[Entry Points]            q1.py … q6.py (Orchestrate and output JSON to console; q6 writes JSON + CSV files)\n                                │\n                                ▼\n[Business Logic]   securehealth/services/ (Pure functions for math \u0026 exclusion filters)\n                                │\n                                ▼\n[Domain Models]     securehealth/models/ (Strict validation schemas via Pydantic v2)\n                                ▲\n                                │\n[Data Ledger]         securehealth/data/ (Centralized ground-truth contract configurations)\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshiin%2Fandersen-trial-task","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakshiin%2Fandersen-trial-task","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakshiin%2Fandersen-trial-task/lists"}