include Uganda Parliament Structure (analysis doc)

src/config/uganda_entity_structure.txt

@@ -0,0 +1,125 @@
+UGANDA PUBLIC ENTITIES STRUCTURE
+================================
+(Source: Office of the Auditor General — List of Entities as at end of 2022)
+Total PDEs (Procuring and Disposing Entities): 1,514
+
+
+1. ENTITY CATEGORIES
+---------------------
+
+The Uganda Auditor General audits public entities grouped into these categories:
+
+A) MINISTRIES (21)
+   Central government ministries, e.g.:
+   - Ministry of Finance, Planning and Economic Development
+   - Ministry of Health
+   - Ministry of Education and Sports
+   - Ministry of Agriculture, Animal Industry and Fisheries
+   - Ministry of Defence and Veteran Affairs
+
+B) BOARDS, COMMISSIONS, COUNCILS, AGENCIES, STATE ENTERPRISES & STATUTORY BODIES (156 combined)
+   Sub-categories:
+   - Boards (4): e.g. Uganda National Examinations Board, Uganda Tourism Board
+   - Commissions (13): e.g. Electoral Commission, Uganda Human Rights Commission
+   - Councils (8): e.g. National Council of Sports, National Council for Higher Education
+   - Government Agencies (23): e.g. Uganda Police Force, Office of the Prime Minister, Parliament of Uganda
+   - State Enterprises (24): e.g. Bank of Uganda, Uganda Airlines, National Water & Sewerage Corporation
+   - Statutory Bodies (34): e.g. Uganda Revenue Authority, KCCA, National Roads Authority, Civil Aviation Authority
+
+C) MISSIONS (34)
+   Ugandan embassies, high commissions, and consulates abroad, e.g.:
+   - Permanent Mission of Uganda to the UN, New York
+   - Uganda High Commission in Kenya, Nairobi
+   - Uganda Embassy in the United States of America, Washington
+
+D) DISTRICT LOCAL GOVERNMENTS (135)
+   Each district has a District Local Government (DLG), e.g.:
+   - Gulu DLG, Kampala (under KCCA), Mukono DLG, Bushenyi DLG
+
+E) CITY COUNCILS (10)
+   Urban authorities with city status:
+   - Arua, Fort Portal, Gulu, Hoima, Jinja, Lira, Masaka, Mbale, Mbarara, Soroti
+
+F) MUNICIPAL COUNCILS (31)
+   Sub-county level urban areas, e.g.:
+   - Entebbe, Kabale, Kasese, Mukono, Tororo, Moroto
+
+G) PUBLIC HOSPITALS (25)
+   Regional referral and national referral hospitals, e.g.:
+   - Mulago National Referral Hospital
+   - Gulu Regional Referral Hospital
+   - Mbarara Regional Referral Hospital
+
+H) PUBLIC UNIVERSITIES & TERTIARY INSTITUTIONS (69)
+   - Universities (14): e.g. Makerere University, Gulu University, Kyambogo University
+   - Tertiary Institutions (47): e.g. Uganda Management Institute, Law Development Centre
+
+I) PUBLIC SECONDARY SCHOOLS (1,033)
+   Mostly not individually audited; covered in bulk reports.
+
+
+2. MAPPING TO QDRANT 'source' FILTER VALUES
+--------------------------------------------
+
+Our database uses a simplified 'source' field. Here is how the entity categories map:
+
+  "Ministry, Department and Agency" (MDA)
+    <- Ministries
+    <- Boards, Commissions, Councils, Agencies, State Enterprises, Statutory Bodies
+    <- Missions
+    <- Universities & Tertiary Institutions
+
+  "Local Government"
+    <- District Local Governments (DLGs)
+    <- City Councils
+    <- Municipal Councils
+
+  "Hospital"
+    <- Public Hospitals (Regional Referral, National Referral)
+
+  "Project"
+    <- Specific government projects (cross-cutting, often multi-year)
+
+  "Value for Money"
+    <- VFM audit reports (thematic, not entity-specific)
+
+  "Consolidated"
+    <- The annual consolidated Auditor General's report
+
+
+3. KEY STRUCTURAL NOTES FOR AGENT REASONING
+--------------------------------------------
+
+- "Ministry" or "MDA" queries should search source="Ministry, Department and Agency"
+- "Local Government" includes DLGs + City Councils + Municipal Councils, all indexed by 'district' name
+- City Councils (10 cities) and Municipal Councils (31 towns) are DISTINCT from District Local Governments
+  but share the same 'source' = "Local Government" and may share the 'district' name
+- Hospitals are a separate audit category — they have their own 'source' = "Hospital"
+- Universities and Tertiary Institutions are audited under MDA, NOT Local Government
+- "Project" reports are cross-cutting (e.g. "Uganda Road Fund", "Rural Electrification") — they span
+  multiple districts/entities and typically don't have a single 'district' value
+- Some entities like KCCA (Kampala Capital City Authority) are statutory bodies but deeply tied to
+  local government functions — they appear under MDA in official classification
+
+- When a user says "government agencies" they likely mean the broader MDA category
+- When they say "local councils" or "district reports" they mean source="Local Government"
+- "VFM" or "value for money" audits are thematic/performance audits, not compliance audits
+
+
+4. METADATA GAPS IN QDRANT (as of BAAI-bge-m3-full)
+-----------------------------------------------------
+
+  source="Local Government" (961 files):
+    - DLG files (676): ALL have 'district' metadata populated
+    - City Council files (48): NONE have 'district' metadata
+    - Municipal Council files (106): NONE have 'district' metadata
+    - 46 hospital files are MISCLASSIFIED under source="Local Government"
+    - 85 other files (divisions, old naming): ~66% have district
+
+  source="Ministry, Department and Agency" (731 files): 'district' is NOT populated
+  source="Hospital" (36 files): 'district' is NOT populated
+  source="Project" (86 files): 'district' is NOT populated (cross-cutting)
+  source="Value for Money" (166 files): Some have 'district', most don't
+
+  Entity sub-type (DLG vs City Council vs Ministry etc) is NOT stored in metadata
+  but CAN BE INFERRED from filename patterns via src/utils/entity_type.py.