harkon/ai-tax-agent
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit
Some checks failed
CI/CD Pipeline / Code Quality & Linting (push) Has been cancelled
Details
CI/CD Pipeline / Policy Validation (push) Has been cancelled
Details
CI/CD Pipeline / Test Suite (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-coverage) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-extract) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-firm-connectors) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-forms) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-hmrc) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-ingestion) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-kg) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-normalize-map) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-ocr) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-rag-indexer) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-rag-retriever) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-reason) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (svc-rpa) (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Images (ui-review) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-coverage) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-extract) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-kg) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (svc-rag-retriever) (push) Has been cancelled
Details
CI/CD Pipeline / Security Scanning (ui-review) (push) Has been cancelled
Details
CI/CD Pipeline / Generate SBOM (push) Has been cancelled
Details
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
Details
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Details
CI/CD Pipeline / Notifications (push) Has been cancelled
Details

Browse Source
This commit is contained in:
harkon
2025-10-11 08:41:36 +01:00
commit b324ff09ef
276 changed files with 55220 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

405
config/coverage.yaml Normal file
View File

@@ -0,0 +1,405 @@
# FILE: config/coverage.yaml
version: "1.0"
jurisdiction: "UK"
tax_year: "2024-25"
tax_year_boundary:
start: "2024-04-06"
end: "2025-04-05"
defaults:
confidence_thresholds:
ocr: 0.82
extract: 0.85
date_tolerance_days: 30
require_lineage_bbox: true
allow_bank_substantiation: true # when primary statement missing, allow verified bank YTD + reconciliation
document_kinds:
# canonical kinds used by extractor/classifier (map your classifier labels to these)
- P60
- P45
- P11D
- PayslipMonthly
- FinalPayslipYTD
- EmploymentContract
- AccountsPAndL
- AccountsBalanceSheet
- CapitalAllowancesSchedule
- MileageLog
- LettingAgentStatements
- TenancyLedger
- MortgageInterestCertificate
- OwnershipShareProof
- OccupancyLog
- BookingsCalendar
- BankStatements
- BuildingSocietyInterestCert
- BankInterestAnnualStatement
- DividendVouchers
- ConsolidatedTaxVoucher
- SLCAnnualStatement
- PensionContributionStatement
- GiftAidStatement
- ForeignIncomeStatement
- OverseasTaxCreditStatement
- TrustDistributionStatement
- EstateR185
- CGT_BrokerAnnualReport
- CGT_Computation
- RemittanceBasisWorkpaper
- ResidenceEvidence
- HMRC_CodingNotice
- HMRC_PaymentOnAccount
- OtherSupportingDoc
guidance_refs:
# Handy lookup keys used by AskClarifyingQuestion; keep them high-level & stable
SA100_Notes_2025: { doc_id: "SA150-Notes-2025", kind: "Notes" }
SA102_Notes_2025: { doc_id: "SA102-Notes-2025", kind: "Notes" }
SA103S_Notes_2025: { doc_id: "SA103S-Notes-2025", kind: "Notes" }
SA103F_Notes_2025: { doc_id: "SA103F-Notes-2025", kind: "Notes" }
SA105_Notes_2025: { doc_id: "SA105-Notes-2025", kind: "Notes" }
SA106_Notes_2025: { doc_id: "SA106-Notes-2025", kind: "Notes" }
SA107_Notes_2025: { doc_id: "SA107-Notes-2025", kind: "Notes" }
SA108_Notes_2025: { doc_id: "SA108-Notes-2025", kind: "Notes" }
SA109_Notes_2025: { doc_id: "SA109-Notes-2025", kind: "Notes" }
SA110_Notes_2025: { doc_id: "SA110-Notes-2025", kind: "Notes" }
triggers:
# Evaluate against KG & intake flags to decide which schedules apply
SA102:
any_of:
- exists: IncomeItem[type="Employment"]
- taxpayer_flag: has_employment
SA103S:
any_of:
- exists: IncomeItem[type="SelfEmployment" AND turnover_lt_vat_threshold=true]
- taxpayer_flag: is_self_employed_short
SA103F:
any_of:
- exists: IncomeItem[type="SelfEmployment" AND turnover_ge_vat_threshold=true]
- taxpayer_flag: is_self_employed_full
SA105:
any_of:
- exists: IncomeItem[type="UKPropertyRent"]
- taxpayer_flag: has_property_income
SA106:
any_of:
- exists: IncomeItem[type IN ["ForeignInterest","ForeignDividends","ForeignEmployment","EEA_FHL","OverseasProperty"]]
- taxpayer_flag: has_foreign_income
SA107:
any_of:
- exists: TrustDistribution
- exists: EstateIncome
- taxpayer_flag: has_trust_or_estate_income
SA108:
any_of:
- exists: CapitalGain
- taxpayer_flag: has_disposals
SA109:
any_of:
- taxpayer_flag: claims_remittance_basis
- exists: NonUKResident
SA110:
any_of:
- filing_mode: paper
- taxpayer_flag: wants_manual_calculation
schedules:
SA102: # Employment
guidance_hint: SA102_Notes_2025
evidence:
- id: P60
role: REQUIRED
boxes: ["SA102_b1", "SA102_b2"] # pay and UK tax taken off
acceptable_alternatives: ["P45", "FinalPayslipYTD"]
validity:
within_tax_year: true
reasons:
short: "P60 (or P45/final payslip) provides year-to-date pay and PAYE tax figures for boxes 1–2."
- id: P11D
role: CONDITIONALLY_REQUIRED
condition: exists(BenefitInKind=true)
boxes:
[
"SA102_b9",
"SA102_b10",
"SA102_b11",
"SA102_b12",
"SA102_b13",
"SA102_b14",
"SA102_b15",
"SA102_b16",
"SA102_b17",
"SA102_b18",
"SA102_b19",
"SA102_b20",
]
acceptable_alternatives: ["EmployerStatement"]
validity:
available_by: "2025-07-06"
reasons:
short: "P11D carries benefits/expenses that map to boxes 9–20 when not payrolled."
- id: SLCAnnualStatement
role: OPTIONAL
boxes: ["SA102_b21", "SA102_b21_1"]
reasons:
short: "Student/Postgrad loan indicators and plan types where applicable."
- id: PayslipMonthly
role: OPTIONAL
boxes: ["SA102_b3"] # tips/other payments not on P60
acceptable_alternatives: []
- id: EmploymentContract
role: OPTIONAL
boxes: []
reasons:
short: "Used only for disambiguation (OFF-PAYROLL/IR35, director)."
cross_checks:
- name: "PAYE Reconcile"
logic: "Sum(payrolled_BIKs_excluded_from_SLR) handled; P60 box totals = SA102_b1; PAYE tax = SA102_b2 within ±£1."
SA103S: # Self-employment (short)
guidance_hint: SA103S_Notes_2025
evidence:
- id: AccountsPAndL
role: REQUIRED
boxes: ["SA103S_b9", "SA103S_b15", "SA103S_b28"]
reasons:
short: "Turnover and allowable expenses supporting net profit figures."
- id: BankStatements
role: REQUIRED
boxes: ["SA103S_b9", "SA103S_b11", "SA103S_b17"]
reasons:
short: "Bank corroboration of takings/expenses (cash basis or traditional)."
- id: CapitalAllowancesSchedule
role: CONDITIONALLY_REQUIRED
condition: exists(ExpenseItem[category='CapitalAllowances'])
boxes: ["SA103S_b49"]
- id: MileageLog
role: OPTIONAL
boxes: ["SA103S_b20"]
- id: HMRC_CodingNotice
role: OPTIONAL
boxes: []
reasons:
short: "Basis period changes or coding interactions."
selection_rule:
prefer_short_if: "turnover < VAT_threshold AND no_complex_adjustments"
else_use: "SA103F"
SA103F: # Self-employment (full)
guidance_hint: SA103F_Notes_2025
evidence:
- id: AccountsPAndL
role: REQUIRED
boxes: ["SA103F_b15", "SA103F_b31", "SA103F_b73"]
- id: AccountsBalanceSheet
role: REQUIRED
boxes: []
- id: BankStatements
role: REQUIRED
boxes: ["SA103F_b15", "SA103F_b31"]
- id: CapitalAllowancesSchedule
role: CONDITIONALLY_REQUIRED
condition: exists(ExpenseItem[category='CapitalAllowances'])
boxes: ["SA103F_b50", "SA103F_b52", "SA103F_b55", "SA103F_b57"]
- id: MileageLog
role: OPTIONAL
boxes: ["SA103F_b20"]
notes:
long_form_needed_if:
- "turnover >= VAT_threshold"
- "claims overlap adjustments, averaging, or multiple trades"
SA105: # UK Property (incl. UK FHL)
guidance_hint: SA105_Notes_2025
evidence:
- id: LettingAgentStatements
role: REQUIRED
boxes: ["SA105_b5", "SA105_b20", "SA105_b29"] # income and totals; totals vs. sum of expenses
acceptable_alternatives: ["TenancyLedger", "BankStatements"]
reasons:
short: "Gross rents, fees and charges per-year by property/portfolio."
- id: MortgageInterestCertificate
role: CONDITIONALLY_REQUIRED
condition: exists(ExpenseItem[category='FinanceCosts'])
boxes: ["SA105_b44"] # feeds SA110 basic-rate credit
- id: OwnershipShareProof
role: CONDITIONALLY_REQUIRED
condition: property_joint_ownership=true
boxes: ["SA105_b3"]
- id: OccupancyLog
role: CONDITIONALLY_REQUIRED
condition: candidate_FHL=true
boxes: ["SA105_b5", "SA105_b20"]
acceptable_alternatives: ["BookingsCalendar"]
- id: BankStatements
role: OPTIONAL
boxes: ["SA105_b20", "SA105_b29"]
cross_checks:
- name: "Property Income Allowance Gate"
logic: "If SA105_b20.1 claimed then no expense boxes 24–29 or FHL expense boxes 6–12 allowed."
SA106: # Foreign
guidance_hint: SA106_Notes_2025
evidence:
- id: ForeignIncomeStatement
role: REQUIRED
boxes: ["SA106_b1", "SA106_b2", "SA106_b3", "SA106_b5"]
reasons:
short: "Dividends/interest/overseas employment; gross and tax paid."
- id: OverseasTaxCreditStatement
role: CONDITIONALLY_REQUIRED
condition: claims_FTCR=true
boxes: ["SA106_b2", "SA106_b5"]
- id: EEA_FHL_OccupancyLog
role: CONDITIONALLY_REQUIRED
condition: exists(IncomeItem[type='EEA_FHL'])
boxes: ["SA106_b14", "SA106_b15"]
- id: BankStatements
role: OPTIONAL
boxes: ["SA106_b1", "SA106_b3"]
notes:
remittance_interaction: "If remittance basis claimed, mirror to SA109."
SA107: # Trusts etc
guidance_hint: SA107_Notes_2025
evidence:
- id: TrustDistributionStatement
role: REQUIRED
boxes: ["SA107_b1", "SA107_b2", "SA107_b3"]
- id: EstateR185
role: CONDITIONALLY_REQUIRED
condition: received_estate_income=true
boxes: ["SA107_b9", "SA107_b10"]
- id: BankStatements
role: OPTIONAL
boxes: []
SA108: # Capital Gains
guidance_hint: SA108_Notes_2025
evidence:
- id: CGT_BrokerAnnualReport
role: REQUIRED
boxes:
[
"SA108_b4",
"SA108_b5",
"SA108_b6",
"SA108_b9",
"SA108_b11",
"SA108_b14",
]
reasons:
short: "Disposals, proceeds, allowable costs, gain breakdowns (residential vs other)."
- id: CGT_Computation
role: REQUIRED
boxes: ["SA108_b28", "SA108_b34"]
- id: BankStatements
role: OPTIONAL
boxes: ["SA108_b4", "SA108_b5"]
special_2024_25:
adjustment_note: "Rate change adjustment for disposals on/after 2024-10-30 may be required."
SA109: # Residence / Remittance
guidance_hint: SA109_Notes_2025
evidence:
- id: ResidenceEvidence
role: REQUIRED
boxes: ["SA109_b1", "SA109_b7", "SA109_b8", "SA109_b9"]
- id: RemittanceBasisWorkpaper
role: CONDITIONALLY_REQUIRED
condition: claims_remittance_basis=true
boxes: ["SA109_b28", "SA109_b39"]
- id: ForeignIncomeStatement
role: OPTIONAL
boxes: ["SA109_b28", "SA109_b39"]
SA110: # Tax calculation summary (paper/manual)
guidance_hint: SA110_Notes_2025
evidence:
- id: HMRC_PaymentOnAccount
role: OPTIONAL
boxes: ["SA110_b10", "SA110_b11"]
- id: HMRC_CodingNotice
role: OPTIONAL
boxes: ["SA110_b7", "SA110_b8", "SA110_b9"]
notes:
online_filing: "If online, SA110 is computed automatically; still store calculation lineage for audit."
SA100: # Core return - savings/dividends/gift aid, etc.
guidance_hint: SA100_Notes_2025
evidence:
- id: BankInterestAnnualStatement
role: CONDITIONALLY_REQUIRED
condition: exists(IncomeItem[type='SavingsInterest'])
boxes: ["SA100_b1"]
- id: DividendVouchers
role: CONDITIONALLY_REQUIRED
condition: exists(IncomeItem[type='Dividends'])
boxes: ["SA100_b2"]
acceptable_alternatives: ["ConsolidatedTaxVoucher"]
- id: PensionContributionStatement
role: CONDITIONALLY_REQUIRED
condition: exists(PensionContribution[relief_method='RAS'])
boxes: ["SA100_b4"]
- id: GiftAidStatement
role: OPTIONAL
boxes: ["SA100_b5"]
status_classifier:
# How we classify found evidence for coverage
present_verified:
min_ocr: 0.82
min_extract: 0.85
date_in_year: true
present_unverified:
min_ocr: 0.60
min_extract: 0.70
date_in_year_or_tolerance: true
conflicting:
conflict_rules:
- "Same doc kind, different totals for same period ±£1"
- "Totals disagree with KG aggregates by >£1"
missing:
default: true
conflict_resolution:
precedence:
[
"LettingAgentStatements",
"P60",
"P11D",
"ConsolidatedTaxVoucher",
"BankStatements",
"ManualEntry",
]
escalation:
to_review: true
reason_templates:
- "Document totals disagree with computed aggregates."
- "Low confidence OCR; request re-upload or alternative."
question_templates:
default:
text: "To complete the {schedule} for {tax_year}, we need {evidence}. These documents support boxes {boxes}. If you don’t have this, you can provide {alternatives}."
why: "{why}. See guidance: {guidance_doc}."
reasons:
P60: "P60 provides your year-end pay and PAYE tax figures for the employment page."
P11D: "P11D lists benefits and expenses that map directly to boxes 9–20 when not payrolled."
LettingAgentStatements: "HMRC expects evidence of gross rents and expenses to support SA105 totals."
MortgageInterestCertificate: "Mortgage interest supports the basic-rate tax reduction computation."
CGT_BrokerAnnualReport: "Brokers’ annual summaries and computations substantiate proceeds, costs and gains."
privacy:
# Ensure we never index PII into vectors
vector_pii_free: true
redact_patterns:
- NI_Number
- UTR
- IBAN
- SortCode
- AccountNumber
- Email
- Phone