Department History Timeline API

[sehansi-9]

This PR introduces a new endpoint to fetch the historical timeline of a department, tracking its movements across different ministries and the ministers appointed during those periods.

• Resolves renamed department lineage using Breadth-first search
• Identifies the overlapping time periods between person - minister - department
• Detects gaps in ministerial appointments and fills them with active president during the time
• Collapses consecutive entries where Minister name and the Person name remain identical (even if minister IDs change)
• Includes test cases and API contract

closes #36

[gemini-code-assist]

Summary of Changes

Hello @sehansi-9, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a significant new feature: an API to provide a detailed historical timeline for any given department. It addresses the complex challenge of tracking departmental changes, ministerial appointments, and historical gaps by intelligently processing relational data. The implementation includes robust data fetching, enrichment, and consolidation mechanisms to present a coherent and accurate historical view, ensuring data integrity and user-friendly output.

Highlights

• New API Endpoint: Introduced a new GET endpoint /v1/organisation/department-history/{department_id} to retrieve the historical timeline of a department.
• Department Lineage Resolution: Implemented a Breadth-First Search (BFS) algorithm to resolve and track renamed department lineage.
• Ministerial Appointment Logic: Developed logic to identify overlapping time periods between persons, ministers, and departments, and to detect and fill gaps in ministerial appointments with active presidential data.
• Data Consolidation: Added functionality to collapse consecutive timeline entries where the minister name and person name remain identical, even if minister IDs change.
• API Contract and Tests: Included the OpenAPI contract for the new endpoint and comprehensive test cases to validate the service logic.

Changelog

• gi_service/contract/rest/organisation_api_contract.yaml
  • Added the OpenAPI specification for the new /v1/organisation/department-history/{department_id} GET endpoint.
• src/routers/organisation_router.py
  • Implemented the new asynchronous GET route /department-history/{department_id} to expose the department history timeline functionality.
• src/services/organisation_service.py
  • Introduced the department_history_timeline method to orchestrate the fetching and processing of department history.
  • Added helper methods _get_renamed_lineage, _fetch_and_map_entities, and _fetch_and_map_relations for efficient data retrieval and mapping.
  • Implemented logic for filtering, enriching, gap detection, and collapsing historical entries based on various criteria.
• test/test_organisation_service.py
  • Added new asynchronous unit tests for test_department_history_timeline_success to verify the core functionality.
  • Included test_department_history_timeline_collapsing to ensure correct consolidation of consecutive entries.
  • Created tests for helper functions: test_get_renamed_lineage_chain, test_get_renamed_lineage_no_renaming, test_fetch_and_map_entities_success, test_fetch_and_map_entities_partial_failure, test_fetch_and_map_relations_success, and test_fetch_and_map_relations_with_errors.

Activity

• The pull request was opened by sehansi-9.
• The changes introduce a new API endpoint and its corresponding service logic and tests.
• The pull request addresses and closes issue Department History API Endpoint #36.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new API endpoint to retrieve the historical timeline of a department. The implementation is comprehensive, covering department renaming, ministerial appointments, and handling of appointment gaps. I've provided a few suggestions to improve performance, code structure, and the API contract for better usability. The tests are well-written but could be made more robust against changes in asynchronous execution order. Overall, this is a solid contribution.

[zaeema-n]

Can't we run every iteration of this loop in parallel?

[sehansi-9]

since there are no API calls and the iterations are purely computational in this loop, would it make a difference to use async io? or is there a different approach?

[zaeema-n]

Since this loop has multiple nested loops in it my understanding is that it would take a lot of time to complete each iteration so since the iterations are independent we can do them in parallel. However, I suppose this depends on the data as well. @ChanukaUOJ what do you think?

[sehansi-9]

this will be addressed here #93