Create app from nganga-ai/dikoka repository

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+chroma_db/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text
+data/chroma_db/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,173 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+*.out

app.py

@@ -0,0 +1,138 @@
+import os
+import random
+from typing import List
+
+import gradio as gr
+
+from src.database import load_dataset, load_final_summaries, load_questions
+from src.rag_pipeline.rag_system import RAGSystem
+
+os.environ["TOKENIZERS_PARALLELISM"] = "true"
+
+
+class ChatInterface:
+    """
+    A class to create and manage the chat interface for the Dikoka AI assistant.
+    """
+
+    def __init__(self, rag_system: RAGSystem):
+        """
+        Initialize the ChatInterface with a RAG system.
+        """
+        self.rag_system = rag_system
+        self.history_depth = int(os.getenv("MAX_MESSAGES") or 5) * 2
+        self.questions = []
+        self.summaries = []
+
+    def respond(self, message: str, history: List[List[str]]):
+        """
+        Generate a response to the user's message using the RAG system.
+        """
+        result = ""
+        history = [
+            (turn["role"], turn["content"]) for turn in history[-self.history_depth :]
+        ]
+        for text in self.rag_system.query(message, history):
+            result += text
+            yield result
+        return result
+
+    def sample_questions(self):
+        """
+        Sample a few random questions from the loaded questions.
+        """
+        random_questions = random.sample(self.questions, 3)
+        example_questions = "\n".join(
+            ["## Examples of questions"]
+            + [f"- {question}" for question in random_questions]
+        )
+        return example_questions
+
+    def sample_summaries(self):
+        """
+        Sample a random summary from the loaded summaries.
+        """
+        random_summary = random.choice(self.summaries)
+        return random_summary
+
+    def load_data(self, lang: str):
+        """
+        Load questions and summaries for the specified language.
+        """
+        self.questions = load_questions(lang)
+        self.summaries = load_final_summaries(lang)
+
+    def create_interface(self) -> gr.Blocks:
+        """
+        Create the Gradio interface for the chat application.
+        """
+        self.load_data("fr")
+
+        description = (
+            "Dikoka an AI assistant providing information on the Franco-Cameroonian Commission's"
+            " findings regarding France's role and engagement in Cameroon during the suppression"
+            " of independence and opposition movements between 1945 and 1971.\n\n"
+            "🌟 **Code Repository**: [Dikoka GitHub](https://github.com/Nganga-AI/dikoka)"
+        )
+
+        with gr.Blocks() as demo:
+            with gr.Row(equal_height=True):
+                with gr.Column():
+                    with gr.Row():
+                        with gr.Column():
+                            dpd = gr.Dropdown(
+                                choices=["fr", "eng"],
+                                value="fr",
+                                label="Choose language",
+                            )
+                            dpd.change(self.load_data, inputs=dpd)
+                        with gr.Column(scale=2):
+                            gr.Markdown("## Summary")
+                    with gr.Row():
+                        with gr.Column():
+                            self.sample_resume = gr.Markdown(self.sample_summaries())
+                    with gr.Row():
+                        sample_summary = gr.Button("Sample Summary")
+                        sample_summary.click(
+                            fn=self.sample_summaries,
+                            inputs=[],
+                            outputs=self.sample_resume,
+                        )
+                with gr.Column(scale=2):
+                    gr.ChatInterface(
+                        fn=self.respond,
+                        type="messages",
+                        title="Dikoka",
+                        description=description,
+                    )
+            with gr.Row():
+                self.example_questions = gr.Markdown(self.sample_questions())
+            with gr.Row():
+                sample_button = gr.Button("Sample New Questions")
+                sample_button.click(
+                    fn=self.sample_questions,
+                    inputs=[],
+                    outputs=self.example_questions,
+                )
+        return demo
+
+
+def get_rag_system(top_k_documents):
+    """
+    Initialize and return a RAG system with the specified number of top documents.
+    """
+    rag = RAGSystem("data/chroma_db", batch_size=64, top_k_documents=top_k_documents)
+    if not os.path.exists(rag.vector_store_management.persist_directory):
+        documents = load_dataset(os.getenv("LANG"))
+        rag.initialize_vector_store(documents)
+    return rag
+
+
+# Usage example:
+if __name__ == "__main__":
+    top_k_docs = int(os.getenv("N_CONTEXT") or 5)
+    rag_system = get_rag_system(top_k_documents=top_k_docs)
+
+    chat_interface = ChatInterface(rag_system)
+    demo = chat_interface.create_interface()
+    demo.launch(share=False)

chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/data_level0.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f4de2593e1b32f66ecf2d58e107a40a949249409fd88eacce4fa6d5af28bf04
+size 4656000

chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/header.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a112506f487c99e6ff26e0319a7743a8ecaecf4c640132cd07af9aff04135984
+size 100

chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/index_metadata.pickle

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aff0347f05636ae8947bb372ffe6386043ad6c35909370c9cd74ef8127acf388
+size 229997

chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/length.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:be5b1c36a9a63d9cca9bbaaf700ff548646596c0951f98f35502b57333eadad7
+size 16000

chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/link_lists.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:84b95327037dc7b063da5af4957a00979a0cfc710bd70372ac92f0d4004e2183
+size 34836

chroma_db/chroma.sqlite3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9efbbbbc951f272bf4eb05b014fdfc281a99c1ac8ac8913cfe5b953410622c6c
+size 50978816

data/chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/data_level0.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f4de2593e1b32f66ecf2d58e107a40a949249409fd88eacce4fa6d5af28bf04
+size 4656000

data/chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/header.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a112506f487c99e6ff26e0319a7743a8ecaecf4c640132cd07af9aff04135984
+size 100

data/chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/index_metadata.pickle

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aff0347f05636ae8947bb372ffe6386043ad6c35909370c9cd74ef8127acf388
+size 229997

data/chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/length.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:be5b1c36a9a63d9cca9bbaaf700ff548646596c0951f98f35502b57333eadad7
+size 16000

data/chroma_db/4daca867-b763-4a6b-8b5b-fdf70e3d9ead/link_lists.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:84b95327037dc7b063da5af4957a00979a0cfc710bd70372ac92f0d4004e2183
+size 34836

data/chroma_db/chroma.sqlite3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9efbbbbc951f272bf4eb05b014fdfc281a99c1ac8ac8913cfe5b953410622c6c
+size 50978816

requirements.txt

@@ -0,0 +1,15 @@
+langchain-ollama==0.2.2
+langchain-groq==0.2.3
+langchain-community==0.3.14
+langchain-chroma==0.1.4
+langchain-huggingface
+langchain==0.3.14
+ollama==0.4.5
+chromadb==0.5.23
+# OCR
+tqdm==4.67.1
+gradio
+rank_bm25==0.2.2
+groq==0.15.0
+tiktoken==0.8.0
+einops==0.8.0

saved_summaries/eng/final_summary_297054.txt

@@ -0,0 +1,9 @@
+In the mid-20th century, Cameroon became a focal point for anti-colonial tensions as French authorities sought to suppress the Union des Populations du Cameroun (UPC), a key nationalist movement pushing for independence. During this period, Roland Pré, the French Haut-Commissaire, implemented strategic measures aimed at countering UPC influence amidst growing demands for autonomy. This era was marked by increased surveillance and aggressive repression, particularly in regions like Sanaga-Maritime, where leaders such as Achille Mbembe and Ernest Ouandié mobilized resistance through political and military training.
+
+French tactics included deploying armed forces to disrupt protests and arrest demonstrators, resulting in the imprisonment of approximately 47 UPC supporters. These actions highlighted France's determination to maintain colonial control despite international decolonization pressures. Pré's approach combined administrative reforms and military measures, reflecting a broader French strategy to weaken anti-colonial movements by fostering pro-French factions and implementing decentralizing policies.
+
+Parallel to these efforts in Cameroon, France adapted its military strategies globally through the development of "guerre révolutionnaire" or revolutionary warfare. This innovative approach emerged as conventional tactics proved inadequate against insurgencies like those in Algeria and Vietnam. Colonel Charles Lacheroy was instrumental in this strategy, which emphasized psychological operations designed to destabilize existing social orders and erode state authority, combining these with traditional military actions to gain civilian support.
+
+These developments coincided with diplomatic efforts at the United Nations, where intense negotiations over French trusteeship agreements for Cameroon highlighted global tensions between colonial powers and emerging norms of self-governance. During the Fourth Committee sessions in December 1946, delegates criticized France's proposals for inadequately prioritizing Cameroonian interests, advocating for amendments to ensure future administrations were accountable to the UN rather than colonial authorities.
+
+These discussions reflected a broader shift towards decolonization post-World War II, emphasizing local autonomy and international oversight. As global norms increasingly favored self-governance, these diplomatic efforts marked an important step in redefining colonial administration through legal frameworks recognizing indigenous rights and autonomy. Together, these military, political, and diplomatic dynamics illustrate the complexities of resisting colonial rule in mid-20th-century Africa and underscore the persistent struggle for Cameroon's independence within this turbulent historical context.

saved_summaries/eng/final_summary_297054_Volume_2.txt

@@ -0,0 +1,11 @@
+During Cameroon's transition from French colonial rule to independence between 1950s and early 1970s, several complex dynamics unfolded as both nations navigated military autonomy, control, and lingering colonial influences. In December 1960, France aimed to maintain influence over the forming Cameroonian forces through a secretive directive issued by Prime Minister Michel Debré on November 25, bypassing traditional command channels. This created friction within French military hierarchy, particularly between General Sizaire of the CIFFC and other entities, exacerbated when Sizaire learned about the instruction through delayed correspondence from Pierre Messmer in January 1961.
+
+To address these challenges, proposals emerged for restructuring French military presence into two distinct commands: a Mixed Military Force (MMF) under the ambassador's authority and a separate Forces Françaises au Cameroun (FFC), managed by Zone Militaire n°2. This restructuring aimed to streamline operations while safeguarding France’s strategic interests as Cameroon moved towards military independence, highlighting tensions inherent in decolonization.
+
+As Cameroon transitioned further into autonomy during the late 1960s and early 1970s, domestic unrest in France complicated bilateral relations and delayed military support initiatives pursued by President Ahmadou Ahidjo. While Cameroonian officers sought greater sovereignty and younger commanders began exercising independence from French counterparts, regional stability remained a concern. In response, Cameroon expanded its educational opportunities with nations like the USSR and Greece to reduce reliance on French training.
+
+French influence persisted in regions such as Bamiléké, where indirect support continued through logistics and preventive measures despite ongoing tensions over control and command approaches. These dynamics underscored broader post-independence challenges, balancing aspirations for national sovereignty against enduring colonial ties.
+
+Parallel to these military and political transitions, severe human rights abuses emerged during Cameroon's decolonization process. French-backed forces employed coercive interrogation techniques like the "kalimba" method, involving electric shocks to extract confessions under duress. Such practices were often downplayed in official reports, despite testimonies revealing widespread violence against Cameroonian political figures and continuity of colonial-era repression strategies.
+
+This period reflects broader themes of post-independence transitions, emphasizing challenges in maintaining order while transitioning from oppressive colonial legacies. Acknowledging these historical injustices is crucial to understanding their impact on national identity formation and governance in newly independent states like Cameroon. The synthesis of military restructuring efforts, sovereignty aspirations, and human rights abuses provides a comprehensive overview of the complexities inherent in decolonization.

saved_summaries/eng/level_2_chunk_0_20250202_120459.txt

@@ -0,0 +1,7 @@
+In mid-1950s Cameroon, anti-colonial tensions intensified as French authorities sought to suppress the Union des Populations du Cameroun (UPC). Roland Pré, the French Haut-Commissaire, played a critical role in implementing strategies aimed at countering UPC influence amidst growing demands for independence. This period was marked by strategic confrontations and repressive measures against the UPC.
+
+Key events included increased surveillance and aggressive repression in regions like Sanaga-Maritime, where leaders such as Achille Mbembe and Ernest Ouandié attempted to mobilize resistance through political and military training. French tactics involved deploying armed guards from Douala and Ngambè to disrupt protests and arrest demonstrators, including actions leading to the imprisonment of about 47 UPC supporters.
+
+These incidents highlight the violent nature of the conflict and France's determination to maintain colonial control in response to international decolonization pressures. The events underscored the broader struggle for Cameroon’s independence, illustrating Pré's multifaceted approach that combined administrative reforms and military measures against the anti-colonial movement.
+
+This summary aligns with previous discussions by emphasizing Pré's strategic efforts to dilute UPC influence through fostering pro-French factions and implementing decentralizing policies. These actions were part of a broader French colonial strategy during this turbulent period, reflecting the complexities of resisting colonial rule in mid-20th-century Africa.

saved_summaries/eng/level_2_chunk_0_20250202_123011.txt

@@ -0,0 +1,7 @@
+In December 1960, as France transitioned military control to Cameroon by January 1, 1961, significant challenges emerged, particularly highlighted in an "Instruction personnelle et secrète" issued on November 25 by French Prime Minister Michel Debré. This directive aimed to maintain French influence over the newly forming Cameroonian forces during decolonization but bypassed traditional military command channels, creating friction within the French military hierarchy.
+
+The confusion primarily stemmed from unclear responsibilities between the Command of Forces Interarmées Françaises au Cameroun (CIFFC), led by General Sizaire, and other French military entities. This discord was exacerbated when General Sizaire only learned about the instruction through a letter dated January 2, 1961, sent by Minister Pierre Messmer, who criticized its secretive nature.
+
+To address these challenges, there were calls for clearer delineation of command structures to prevent further conflicts. In response, Pierre Messmer proposed restructuring French military presence into two distinct commands: a Mixed Military Force (MMF) under the ambassador's authority and a separate command for Forces Françaises au Cameroun (FFC), overseen by Zone Militaire n°2 (Zom n°2). These measures aimed to streamline operations and solidify France's strategic interests as Cameroon moved towards military independence.
+
+Overall, this period highlights the complexities and tensions inherent in decolonization, particularly regarding maintaining influence while transitioning control over military forces.

saved_summaries/eng/level_2_chunk_1_20250202_120509.txt

@@ -0,0 +1,7 @@
+In the mid-1950s, Cameroon experienced heightened anti-colonial tensions as French authorities intensified efforts to suppress the Union des Populations du Cameroun (UPC), a key nationalist movement. Under Roland Pré, the French Haut-Commissaire, strategic measures were implemented to counter UPC influence amid growing independence demands. This period was characterized by increased surveillance and aggressive repression, particularly in regions like Sanaga-Maritime.
+
+Leaders such as Achille Mbembe and Ernest Ouandié sought to galvanize resistance through political and military training, prompting French authorities to deploy armed guards from Douala and Ngambè. These forces disrupted protests and led to the arrest of around 47 UPC supporters, highlighting the violent nature of the conflict and France's determination to maintain colonial control.
+
+These events underscored Cameroon’s broader struggle for independence, illustrating Pré's multifaceted strategy that combined administrative reforms with military actions against anti-colonial movements. This approach was part of a larger French colonial strategy during this turbulent period in mid-20th-century Africa, reflecting the complexities faced by those resisting colonial rule.
+
+This summary aligns with previous discussions on Pré’s efforts to weaken UPC influence through pro-French factions and decentralization policies, emphasizing the persistent struggle for Cameroon's independence against international decolonization pressures.

saved_summaries/eng/level_2_chunk_1_20250202_123019.txt

@@ -0,0 +1,7 @@
+In the late 1960s to early 1970s, Cameroon navigated a complex transition towards military autonomy from France, marked by efforts to assert sovereignty while managing residual colonial influences. The process culminated in complete control over its military forces by 1969. Tensions were prevalent between French and Cameroonian officers, particularly as younger Cameroonian commanders began exercising more independence, often disregarding their experienced French counterparts.
+
+During this period, President Ahmadou Ahidjo actively sought enhanced military support from France to ensure regional stability without direct intervention. However, domestic unrest in France during 1968 delayed these efforts, complicating bilateral relations. To address the challenges of relying solely on French military training, Cameroon explored educational opportunities with other nations such as the USSR and Greece.
+
+French involvement remained significant in certain regions like Bamiléké, where indirect support continued through logistics and preventive measures. Despite ongoing tensions over control and differing approaches to command, these agreements underscored the nuanced dynamics between seeking autonomy and maintaining established colonial ties within Cameroon's military sector during decolonization.
+
+This phase reflects broader themes of post-independence transitions, emphasizing both the aspirations for national sovereignty and the enduring complexities of former colonial relationships in shaping new national identities.

saved_summaries/eng/level_2_chunk_2_20250202_120519.txt

@@ -0,0 +1,7 @@
+In the mid-20th century, France adapted its military strategies to address insurgencies during decolonization, particularly through the development of "guerre révolutionnaire" or revolutionary warfare. This approach emerged in response to the limitations of conventional tactics against movements such as those in Algeria and Vietnam. Colonel Charles Lacheroy was instrumental in formulating this strategy, which emphasized a multi-stage process beginning with psychological operations designed to destabilize existing social orders and erode state authority.
+
+Lacheroy's framework highlighted the integration of psychological operations into military planning, aiming to influence public perception and loyalty to either gain support or suppress insurgencies. His insights were informed by observations from conflicts in Vietnam and Algeria, where insurgents effectively utilized non-military tactics against colonial powers. During the Algerian War of Independence, these strategies were combined with traditional combat operations to both engage insurgents and win civilian "hearts and minds."
+
+The text underscores a pivotal shift in military history as France sought to address modern insurgency complexities through a blend of psychological and conventional warfare techniques. This adaptation was crucial for maintaining control over its colonies during an era marked by increasing demands for independence.
+
+This summary aligns with previous discussions on French colonial strategies, focusing on the broader context of Cameroon's anti-colonial struggles in the 1950s, as outlined earlier. The emphasis here is on France's evolving military doctrine to counter nationalist movements like the UPC (Union des Populations du Cameroun) amid growing international pressures for decolonization.

saved_summaries/eng/level_2_chunk_2_20250202_123028.txt

@@ -0,0 +1,7 @@
+The text provides an in-depth examination of the coercive interrogation methods employed by French-backed forces, particularly the Bataillon Mixte Malgache (BMM), during Cameroon's transition from colonial rule to independence in the 1950s and early 1960s. These methods included brutal tactics such as forced confessions under duress, prominently featuring the "kalimba" method which involved electric shocks intended to extract information regardless of suspects' well-being.
+
+Despite their severity, official reports frequently downplayed or omitted these coercive practices, portraying suspect cooperation as voluntary following persuasion by BMM agents. Specific incidents, including interrogations at places like Fort Kéniéba involving electric shock tactics, highlight the harsh treatment detainees endured during this period.
+
+The text underscores scholarly critiques and personal testimonies that reveal extensive violence against Cameroonian political figures, reflecting a continuity of colonial-era repression strategies despite efforts to develop localized police training. These abuses contributed to broader patterns of oppression in post-colonial Cameroon, emphasizing the need for historical acknowledgment and justice for these human rights violations.
+
+This account fits into a larger narrative of transitioning from colonial rule while grappling with enduring influences and practices inherited from that period, which affected national identity formation and governance in newly independent states.

saved_summaries/eng/level_2_chunk_3_20250202_120528.txt

@@ -0,0 +1,7 @@
+In December 1946, during the United Nations' Fourth Committee sessions in New York, intense negotiations centered on France's proposed trusteeship agreements for Cameroon. Over a span of ten days, delegates scrutinized eight draft agreements and considered 229 amendment proposals, reflecting global tensions between colonial powers and emerging norms of self-governance.
+
+Delegates criticized French drafts for inadequately prioritizing the interests and autonomy of Cameroon’s inhabitants, with concerns raised about vague language that could contradict the UN's goal to establish genuine local governance. Representatives from nations like India, Haiti, and Egypt highlighted discrepancies between these colonial drafts and the principles of self-determination outlined in the UN Charter. They advocated for amendments ensuring that any future administration would be accountable to the United Nations rather than colonial powers such as France.
+
+Proposals aimed at enhancing local autonomy and oversight under international law gained traction, reflecting a broader shift toward decolonization post-World War II. These discussions marked an important step towards redefining colonial administration through legal frameworks recognizing indigenous rights and autonomy, setting the stage for Cameroon's eventual path to independence.
+
+This summary continues from previous discussions on French colonial strategies by highlighting pivotal diplomatic efforts at the UN that reshaped international approaches to decolonization, emphasizing how emerging norms increasingly favored self-governance.

saved_summaries/eng/level_2_chunk_3_20250202_123035.txt

@@ -0,0 +1,5 @@
+The text continues to explore severe human rights abuses during Cameroon's transition from colonial rule to independence, focusing on coercive interrogation methods employed by French-backed forces, including British collaboration. Techniques like the "kalimba" method involved electric shocks aimed at extracting information with little regard for detainees' well-being. Official reports often downplayed these brutal practices, framing suspect confessions as voluntary.
+
+Specific incidents and testimonies reveal the harsh realities of interrogation tactics, such as those at Fort Kéniéba, illustrating a pattern of violence against Cameroonian political figures that mirrors colonial repression strategies. These abuses are contextualized within efforts to establish localized police forces in post-colonial Cameroon, highlighting the challenges of maintaining order while transitioning from colonial practices.
+
+The text emphasizes the need for acknowledging these historical injustices to fully understand this period in Cameroonian history, underscoring broader patterns of oppression and their impact on national identity and governance. This narrative fits into a larger context of grappling with colonial legacies in newly independent states.

saved_summaries/fr/final_summary_297054.txt

@@ -0,0 +1,9 @@
+Au milieu du 20ème siècle, le Cameroun est devenu un point focal des tensions anticolonialistes alors que les autorités françaises cherchaient à réprimer l'Union des Populations du Cameroun (UPC), un mouvement nationaliste clé prônant l'indépendance. Pendant cette période, Roland Pré, le Haut-Commissaire français, a mis en œuvre des mesures stratégiques visant à contrer l'influence de l'UPC au milieu des demandes croissantes d'autonomie. Cette ère était marquée par une surveillance accrue et une répression agressive, particulièrement dans des régions comme le Sanaga-Maritime, où des leaders tels qu'Achille Mbembe et Ernest Ouandié ont mobilisé la résistance à travers la formation politique et militaire.
+
+Les tactiques françaises incluaient le déploiement de forces armées pour perturber les manifestations et arrêter les manifestants, entraînant l'emprisonnement d'environ 47 partisans de l'UPC. Ces actions ont souligné la détermination de la France à maintenir le contrôle colonial malgré les pressions internationales en faveur du désengagement colonial. L'approche de Pré combinait des réformes administratives et des mesures militaires, reflétant une stratégie française plus large visant à affaiblir les mouvements anticolonialistes en favorisant des factions pro-françaises et en mettant en œuvre des politiques décentralisatrices.
+
+Parallèlement à ces efforts au Cameroun, la France a adapté ses stratégies militaires à l'échelle mondiale grâce au développement de la "guerre révolutionnaire" ou guerre révolutionnaire. Cette approche innovante est apparue alors que les tactiques conventionnelles se révélaient insuffisantes contre des insurgences comme celles en Algérie et au Vietnam. Le Colonel Charles Lacheroy a joué un rôle instrumental dans cette stratégie, qui mettait l'accent sur les opérations psychologiques conçues pour déstabiliser les ordres sociaux existants et éroder l'autorité de l'État, en combinant ces éléments avec des actions militaires traditionnelles pour obtenir le soutien des civils.
+
+Ces développements ont coïncidé avec des efforts diplomatiques à l'Organisation des Nations Unies, où des négociations intenses sur les accords de tutelle française concernant le Cameroun mettaient en lumière les tensions mondiales entre les puissances coloniales et les nouvelles normes d'autogouvernance. Lors des sessions du Quatrième Comité en décembre 1946, les délégués ont critiqué les propositions de la France pour ne pas prioriser suffisamment les intérêts camerounais, plaidant pour des amendements afin d'assurer que les futures administrations seraient responsables devant l'ONU plutôt que devant les autorités coloniales.
+
+Ces discussions reflétaient un changement plus large vers le désengagement post-Seconde Guerre mondiale, soulignant l'autonomie locale et la surveillance internationale. À mesure que les normes mondiales favorisaient de plus en plus l'autogouvernance, ces efforts diplomatiques marquaient une étape importante dans la redéfinition de l'administration coloniale à travers des cadres juridiques reconnaissant les droits et l'autonomie autochtones. Ensemble, ces dynamiques militaires, politiques et diplomatiques illustrent les complexités de la résistance au règne colonial en Afrique au milieu du 20ème siècle et soulignent le combat persistant pour l'indépendance du Cameroun dans ce contexte historique tumultueux.

saved_summaries/fr/final_summary_297054_Volume_2.txt

@@ -0,0 +1,11 @@
+Pendant la transition du Cameroun sous domination coloniale française vers l'indépendance entre les années 1950 et le début des années 1970, plusieurs dynamiques complexes se sont déroulées alors que les deux nations naviguaient dans l'autonomie militaire, le contrôle et les influences coloniales persistantes. En décembre 1960, la France a cherché à maintenir son influence sur les forces camerounaises en formation grâce à une directive secrète émise par le Premier ministre Michel Debré le 25 novembre, contournant les canaux de commandement traditionnels. Cela a créé des tensions au sein de la hiérarchie militaire française, notamment entre le général Sizaire du CIFFC et d'autres entités, exacerbées lorsque Sizaire a appris l'instruction par une correspondance retardée de Pierre Messmer en janvier 1961.
+
+Pour faire face à ces défis, des propositions sont apparues pour restructurer la présence militaire française en deux commandements distincts : une Force Militaire Mixte (FMM) sous l'autorité de l'ambassadeur et une Forces Françaises au Cameroun (FFC), gérée par la Zone Militaire n°2. Cette réorganisation visait à rationaliser les opérations tout en protégeant les intérêts stratégiques de la France alors que le Cameroun se dirigeait vers l'indépendance militaire, mettant en lumière les tensions inhérentes au processus de décolonisation.
+
+À mesure que le Cameroun passait à une autonomie accrue dans les années 1960 et au début des années 1970, les troubles intérieurs en France compliquaient les relations bilatérales et retardèrent les initiatives d'aide militaire poursuivies par le président Ahmadou Ahidjo. Alors que les officiers camerounais cherchaient une plus grande souveraineté et que des commandants plus jeunes commençaient à exercer leur indépendance vis-à-vis de leurs homologues français, la stabilité régionale demeurait une préoccupation. En réponse, le Cameroun a élargi ses opportunités d'éducation avec des nations comme l'URSS et la Grèce pour réduire sa dépendance à la formation française.
+
+L'influence française a persisté dans des régions telles que les Bamiléké, où un soutien indirect est continué grâce au logistique et aux mesures préventives malgré les tensions persistantes sur le contrôle et les approches de commandement. Ces dynamiques ont souligné les défis post-indépendance plus larges, équilibrant les aspirations à la souveraineté nationale contre des liens coloniaux durables.
+
+Parallèlement à ces transitions militaires et politiques, d'importantes violations des droits de l'homme sont apparues pendant le processus de décolonisation du Cameroun. Les forces soutenues par la France ont employé des techniques interrogatoires coercitives comme la méthode "kalimba", impliquant des chocs électriques pour extraire des aveux sous la contrainte. De telles pratiques étaient souvent atténuées dans les rapports officiels, malgré les témoignages révélant une violence généralisée contre les figures politiques camerounaises et la continuité des stratégies de répression de l'ère coloniale.
+
+Cette période reflète les thèmes plus larges des transitions post-indépendance, mettant en évidence les défis pour maintenir l'ordre tout en passant de héritages coloniaux oppressifs. Reconnaître ces injustices historiques est essentiel pour comprendre leur impact sur la formation de l'identité nationale et le gouvernement dans des États nouvellement indépendants comme le Cameroun. La synthèse des efforts de restructuration militaire, des aspirations à la souveraineté et des abus en matière de droits de l'homme fournit un aperçu complet des complexités inhérentes à la décolonisation.

saved_summaries/fr/level_2_chunk_0_20250202_120459.txt

@@ -0,0 +1,7 @@
+Dans le milieu des années 1950 au Cameroun, les tensions anti-coloniales se sont intensifiées alors que les autorités françaises cherchaient à réprimer l'Union des Populations du Cameroun (UPC). Roland Pré, Haut-Commissaire français, a joué un rôle crucial dans la mise en œuvre de stratégies visant à contrer l'influence de l'UPC au milieu des demandes croissantes d'indépendance. Cette période était marquée par des confrontations stratégiques et des mesures répressives contre l'UPC.
+
+Les événements clés incluaient une surveillance accrue et une répression agressive dans des régions comme la Sanaga-Maritime, où des leaders tels qu'Achille Mbembe et Ernest Ouandié tentaient de mobiliser la résistance par le biais d'un entraînement politique et militaire. Les tactiques françaises impliquaient le déploiement de gardes armés de Douala et Ngambè pour perturber les manifestations et arrêter les manifestants, y compris des actions conduisant à l'emprisonnement d'environ 47 partisans de l'UPC.
+
+Ces incidents mettent en évidence la nature violente du conflit et la détermination de la France à maintenir le contrôle colonial face aux pressions internationales pour la décolonisation. Les événements ont souligné la lutte plus large pour l'indépendance du Cameroun, illustrant l'approche multifacette de Pré qui combinait des réformes administratives et des mesures militaires contre le mouvement anti-colonial.
+
+Ce résumé est en accord avec les discussions précédentes en soulignant les efforts stratégiques de Pré pour diluer l'influence de l'UPC en favorisant des factions pro-françaises et en mettant en œuvre des politiques décentralisatrices. Ces actions faisaient partie d'une stratégie coloniale française plus large pendant cette période tumultueuse, reflétant les complexités de la résistance au règne colonial dans l'Afrique du milieu du XXe siècle.

saved_summaries/fr/level_2_chunk_0_20250202_123011.txt

@@ -0,0 +1,7 @@
+En décembre 1960, alors que la France passait le contrôle militaire au Cameroun pour le 1er janvier 1961, des défis importants ont émergé, notamment mis en lumière par une "Instruction personnelle et secrète" émise le 25 novembre par le Premier ministre français Michel Debré. Cette directive visait à maintenir l'influence française sur les forces camerounaises nouvellement formées pendant la décolonisation, mais contournait les canaux de commandement militaire traditionnels, créant des frictions au sein de la hiérarchie militaire française.
+
+La confusion provenait principalement d'une responsabilité floue entre le Commandement des Forces Interarmées Françaises au Cameroun (CIFFC), dirigé par le Général Sizaire, et d'autres entités militaires françaises. Ce désaccord a été exacerbé lorsque le Général Sizaire n'a appris l'instruction que par une lettre datée du 2 janvier 1961 envoyée par le ministre Pierre Messmer, qui critiquait sa nature secrète.
+
+Pour répondre à ces défis, il y avait des appels à une délimitation plus claire des structures de commandement afin d'éviter davantage de conflits. En réponse, Pierre Messmer a proposé de restructurer la présence militaire française en deux commandements distincts : une Force Militaire Mixte (FMM) sous l'autorité de l'ambassadeur et un commandement séparé pour les Forces Françaises au Cameroun (FFC), supervisé par Zone Militaire n°2 (Zom n°2). Ces mesures visaient à rationaliser les opérations et à consolider les intérêts stratégiques de la France alors que le Cameroun se dirigeait vers l'indépendance militaire.
+
+Dans l'ensemble, cette période met en lumière les complexités et tensions inhérentes à la décolonisation, notamment en ce qui concerne le maintien d'une influence tout en passant le contrôle sur les forces militaires.

saved_summaries/fr/level_2_chunk_1_20250202_120509.txt

@@ -0,0 +1,7 @@
+Dans la moitié des années 1950, le Cameroun a connu des tensions anti-coloniales accrues alors que les autorités françaises intensifiaient leurs efforts pour réprimer l'Union des Populations du Cameroun (UPC), un mouvement nationaliste clé. Sous Roland Pré, Haut-Commissaire français, des mesures stratégiques ont été mises en œuvre pour contrer l'influence de l'UPC face à la croissance des demandes d'indépendance. Cette période était caractérisée par une surveillance accrue et une répression agressive, particulièrement dans des régions comme Sanaga-Maritime.
+
+Des leaders tels qu'Achille Mbembe et Ernest Ouandié ont cherché à galvaniser la résistance à travers des formations politiques et militaires, incitant les autorités françaises à déployer des gardes armés depuis Douala et Ngambè. Ces forces ont perturbé les manifestations et conduit à l'arrestation d'environ 47 partisans de l'UPC, soulignant la nature violente du conflit et la détermination de la France à maintenir le contrôle colonial.
+
+Ces événements ont mis en évidence la lutte plus large du Cameroun pour l'indépendance, illustrant la stratégie multifacette de Pré qui combinait réformes administratives avec des actions militaires contre les mouvements anti-coloniaux. Cette approche faisait partie d'une stratégie coloniale française plus large durant cette période tumultueuse en Afrique du milieu du 20ème siècle, reflétant la complexité rencontrée par ceux qui résistaient à l'autorité coloniale.
+
+Ce résumé s'aligne avec les discussions précédentes sur les efforts de Pré pour affaiblir l'influence de l'UPC grâce aux factions pro-françaises et aux politiques de décentralisation, soulignant la lutte persistante du Cameroun pour son indépendance face aux pressions internationales de décolonisation.

saved_summaries/fr/level_2_chunk_1_20250202_123019.txt

@@ -0,0 +1,7 @@
+Dans la fin des années 1960 et le début des années 1970, le Cameroun a navigué à travers une transition complexe vers l'autonomie militaire de la France, marquée par des efforts pour affirmer sa souveraineté tout en gérant les influences coloniales résiduelles. Le processus s'est achevé avec un contrôle complet sur ses forces armées d'ici 1969. Des tensions prévalaient entre les officiers français et camerounais, notamment alors que des commandants camerounais plus jeunes commençaient à exercer une indépendance accrue, souvent en ignorant leurs homologues expérimentés français.
+
+Pendant cette période, le président Ahmadou Ahidjo a activement cherché un soutien militaire renforcé de la France pour assurer la stabilité régionale sans intervention directe. Cependant, les troubles intérieurs en France en 1968 ont retardé ces efforts, compliquant les relations bilatérales. Pour répondre aux défis d'une dépendance exclusive à la formation militaire française, le Cameroun a exploré des opportunités éducatives avec d'autres nations telles que l'URSS et la Grèce.
+
+La participation française est restée significative dans certaines régions comme les Bamiléké, où un soutien indirect continuait à travers la logistique et des mesures préventives. Malgré les tensions persistantes sur le contrôle et les approches divergentes du commandement, ces accords soulignaient les dynamiques nuancées entre la recherche d'autonomie et le maintien de liens coloniaux établis dans le secteur militaire du Cameroun pendant la décolonisation.
+
+Cette phase reflète des thèmes plus larges de transitions post-indépendance, mettant en avant à la fois les aspirations pour une souveraineté nationale et les complexités durables des relations coloniales antérieures dans la formation d'identités nationales nouvelles.

saved_summaries/fr/level_2_chunk_2_20250202_120519.txt

@@ -0,0 +1,7 @@
+Au milieu du 20ème siècle, la France a adapté ses stratégies militaires pour faire face aux insurrections lors de la décolonisation, en particulier à travers le développement de la "guerre révolutionnaire" ou guerre révolutionnaire. Cette approche est apparue en réponse aux limitations des tactiques conventionnelles contre des mouvements tels que ceux en Algérie et au Vietnam. Le colonel Charles Lacheroy a joué un rôle clé dans l'élaboration de cette stratégie, qui mettait l'accent sur un processus multi-étapes commençant par des opérations psychologiques conçues pour déstabiliser les ordres sociaux existants et éroder l'autorité de l'État.
+
+Le cadre de Lacheroy soulignait l'intégration d'opérations psychologiques dans la planification militaire, visant à influencer la perception publique et la loyauté pour gagner le soutien ou réprimer les insurrections. Ses aperçus étaient informés par des observations issues de conflits au Vietnam et en Algérie, où les insurgés utilisaient efficacement des tactiques non militaires contre les puissances coloniales. Pendant la Guerre d'Indépendance algérienne, ces stratégies ont été combinées avec des opérations combattantes traditionnelles pour à la fois engager les insurgés et gagner le "cœur et l'esprit" de la population civile.
+
+Le texte souligne un changement pivot dans l'histoire militaire alors que la France cherchait à aborder les complexités modernes des insurrections grâce à une combinaison de techniques de guerre psychologique et conventionnelle. Cette adaptation était cruciale pour maintenir le contrôle sur ses colonies durant une époque marquée par l'augmentation des demandes d'indépendance.
+
+Ce résumé s'aligne avec les discussions précédentes sur les stratégies coloniales françaises, en se concentrant sur le contexte plus large des luttes anti-coloniales au Cameroun dans les années 1950, comme cela a été décrit précédemment. L'accent est ici mis sur l'évolution de la doctrine militaire française pour contrer les mouvements nationalistes tels que l'UPC (Union des Populations du Cameroun) face aux pressions internationales croissantes en faveur de la décolonisation.

saved_summaries/fr/level_2_chunk_2_20250202_123028.txt

@@ -0,0 +1,7 @@
+Le texte fournit une analyse approfondie des méthodes d'interrogatoire coercitif employées par les forces soutenues par la France, notamment le Bataillon Mixte Malgache (BMM), pendant la transition du Cameroun de l'administration coloniale à l'indépendance dans les années 1950 et au début des années 1960. Ces méthodes incluaient des tactiques brutales telles que les aveux forcés sous la contrainte, notamment la méthode "kalimba" qui impliquait des chocs électriques destinés à extraire des informations indépendamment du bien-être des suspects.
+
+Malgré leur gravité, les rapports officiels minimisaient fréquemment ou omettaient ces pratiques coercitives, présentant la coopération des suspects comme volontaire après avoir été persuadés par des agents du BMM. Des incidents spécifiques, notamment des interrogatoires à Fort Kéniéba impliquant des tactiques de chocs électriques, mettent en évidence le traitement sévère subi par les détenus pendant cette période.
+
+Le texte souligne les critiques savantes et les témoignages personnels qui révèlent une violence étendue contre des figures politiques camerounaises, reflétant une continuité des stratégies de répression de l'ère coloniale malgré les efforts pour développer une formation policière locale. Ces abus ont contribué à des schémas plus larges d'oppression au Cameroun post-colonial, mettant en avant la nécessité de reconnaissance historique et de justice pour ces violations des droits humains.
+
+Ce récit s'intègre dans un récit plus vaste de transition de l'administration coloniale tout en faisant face aux influences durables et pratiques héritées de cette période, qui ont affecté la formation de l'identité nationale et le gouvernement des nouveaux États indépendants.

saved_summaries/fr/level_2_chunk_3_20250202_120528.txt

@@ -0,0 +1,7 @@
+En décembre 1946, lors des sessions du Comité spécial quatrième de l'Organisation des Nations unies à New York, des négociations intenses ont porté sur les accords de tutelle proposés par la France pour le Cameroun. Sur une période de dix jours, les délégués ont examiné huit projets d'accord et considéré 229 propositions d'amendement, reflétant les tensions mondiales entre les puissances coloniales émergentes et les nouvelles normes d'autogouvernement.
+
+Les délégués ont critiqué les projets français pour ne pas avoir suffisamment priorisé les intérêts et l'autonomie des habitants du Cameroun, soulevant des préoccupations concernant un langage flou qui pourrait contredire l'objectif de l'ONU d'établir une véritable gouvernance locale. Les représentants de nations comme l'Inde, Haïti et l'Égypte ont mis en évidence les divergences entre ces projets coloniaux et les principes de libre détermination tels qu'ils sont définis dans la Charte des Nations unies. Ils ont plaidé pour des amendements garantissant que toute future administration serait responsable de l'ONU plutôt que des puissances coloniales telles que la France.
+
+Les propositions visant à renforcer l'autonomie locale et le contrôle sous le droit international ont gagné du terrain, reflétant un changement plus large vers la décolonisation après la Seconde Guerre mondiale. Ces discussions marquaient une étape importante pour redéfinir l'administration coloniale par des cadres juridiques reconnus reconnaissant les droits et l'autonomie autochtones, posant les bases du chemin ultérieur vers l'indépendance du Cameroun.
+
+Ce résumé continue à partir de discussions précédentes sur les stratégies coloniales françaises en soulignant des efforts diplomatiques décisifs à l'ONU qui ont redessiné les approches internationales pour la décolonisation, en mettant en avant comment les normes émergentes favorisaient de plus en plus l'autogouvernement.

saved_summaries/fr/level_2_chunk_3_20250202_123035.txt

@@ -0,0 +1,5 @@
+Le texte continue d'explorer les graves violations des droits de l'homme pendant la transition du Cameroun de la domination coloniale à l'indépendance, en se concentrant sur les méthodes d'interrogatoire coercitives employées par les forces soutenues par la France, y compris la collaboration britannique. Des techniques comme la méthode « kalimba » impliquaient des chocs électriques destinés à extraire des informations sans tenir compte du bien-être des détenus. Les rapports officiels minimisaient souvent ces pratiques brutales, présentant les aveux suspects comme volontaires.
+
+Des incidents spécifiques et des témoignages révèlent la dure réalité des tactiques d'interrogatoire, telles que celles utilisées à Fort Kéniéba, illustrant un schéma de violence contre les figures politiques camerounaises qui reflète les stratégies de répression coloniale. Ces abus sont contextualisés dans le cadre des efforts pour établir des forces de police locales au Cameroun post-colonial, mettant en lumière les défis à relever pour maintenir l'ordre tout en passant des pratiques coloniales.
+
+Le texte insiste sur la nécessité de reconnaître ces injustices historiques pour comprendre pleinement cette période de l'histoire camerounaise, soulignant les schémas plus larges d'oppression et leur impact sur l'identité nationale et le gouvernement. Cette narration s'intègre dans un contexte plus large de lutte avec les héritages coloniaux dans les États nouvellement indépendants.

src/__init__.py

@@ -0,0 +1,6 @@
+import logging
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)

src/database.py

@@ -0,0 +1,20 @@
+import json
+import random
+from glob import glob
+
+from .vector_store.document_loader import load_dataset  # noqa
+
+
+def load_questions(language="fr"):
+    raw: dict[str, list[dict[str, str]]] = json.load(
+        open(f"saved_summaries/question_{language}.json")
+    )
+    questions = [example["query"] for _, fqa in raw.items() for example in fqa]
+    return questions
+
+
+def load_final_summaries(language="fr"):
+    files = glob(f"saved_summaries/{language}/*.txt")
+    data = [open(file).read() for file in files]
+    random.shuffle(data)
+    return data

src/rag_pipeline/prompts.py

@@ -0,0 +1,71 @@
+from langchain.prompts.chat import (
+    ChatPromptTemplate,
+    HumanMessagePromptTemplate,
+    MessagesPlaceholder,
+    SystemMessagePromptTemplate,
+)
+
+# ---------------------------------------------------------------------------
+# System Prompt for the RAG Expert on France's Role in Cameroon
+# ---------------------------------------------------------------------------
+system_prompt = """
+You are **Dikoka**, an AI assistant and expert on France’s involvement in Cameroon during the suppression of independence and opposition movements (1945-1971), based on the findings of the Franco-Cameroonian Commission.
+
+**Instructions:**
+- **Answer strictly using the provided context.**
+- **Summarize key points when requested.**
+- **Maintain accuracy and neutrality; avoid speculation or external knowledge.**
+
+**Response Guidelines:**
+1. **Context-Only Answers:** Rely solely on the provided context.
+2. **Insufficient Information:** If details are lacking, reply:
+   > "I do not have enough information to answer this question based on the provided context."
+3. **Language Requests:** If a query is in an African language or asks for a translation, reply:
+   > "I can only provide information in the language of the original context. Could you please rephrase your question in that language?"
+4. **Irrelevant Topics:** For questions not related to:
+   - The Franco-Cameroonian Commission’s findings
+   - France’s role in Cameroon
+   - The historical period (1945-1971)
+   
+   reply:
+   > "I do not have information on that topic based on the provided context. Could you please ask a question related to France’s role in Cameroon between 1945 and 1971?"
+5. **Summaries:** Provide concise, structured summaries (using bullet points or paragraphs) based solely on the context.
+6. **Formatting:** Organize responses using bullet points, numbered lists, and headings/subheadings when appropriate.
+
+Context:
+{context}
+"""
+
+# Define the messages for the main chat prompt
+chat_messages = [
+    MessagesPlaceholder(variable_name="chat_history"),
+    SystemMessagePromptTemplate.from_template(system_prompt),
+    HumanMessagePromptTemplate.from_template(
+        "Answer in the same language as the input:\n{input}"
+    ),
+]
+
+# Create the chat prompt template
+CHAT_PROMPT = ChatPromptTemplate.from_messages(chat_messages)
+
+# ---------------------------------------------------------------------------
+# Prompt for Generating a Standalone Query from Conversation History
+# ---------------------------------------------------------------------------
+standalone_query_instructions = """
+Your task is to generate a standalone query that is fully understandable without any prior conversation context. Follow these steps:
+
+1. Analyze the conversation history and the latest query.
+2. Rephrase the query to include any necessary context from the history (don't answer the query).
+3. If the original query is already standalone, return it as is.
+4. Maintain the original intent in rephrase and language of the query.
+5. Output only the standalone query **without any explanations or extra text**. Only query rephrased are needed.
+"""
+
+# Create the contextual query prompt template
+CONTEXTUEL_QUERY_PROMPT = ChatPromptTemplate.from_messages(
+    [
+        SystemMessagePromptTemplate.from_template(standalone_query_instructions),
+        MessagesPlaceholder(variable_name="chat_history"),
+        HumanMessagePromptTemplate.from_template("{input}"),
+    ]
+)

src/rag_pipeline/rag_system.py

@@ -0,0 +1,110 @@
+import logging
+from typing import List, Optional
+
+from langchain.chains.combine_documents import create_stuff_documents_chain
+from langchain.chains.conversational_retrieval.base import (
+    BaseConversationalRetrievalChain,
+)
+from langchain.chains.history_aware_retriever import (
+    create_history_aware_retriever,
+)
+from langchain.chains.retrieval import create_retrieval_chain
+
+from ..utilities.llm_models import get_llm_model_chat
+from ..vector_store.vector_store import VectorStoreManager
+from .prompts import CHAT_PROMPT, CONTEXTUEL_QUERY_PROMPT
+
+
+class RAGSystem:
+    """
+    Retrieval-Augmented Generation (RAG) system for document retrieval and question answering.
+    """
+
+    def __init__(
+        self,
+        persist_directory_dir="data/chroma_db",
+        batch_size: int = 64,
+        top_k_documents=5,
+    ):
+        """
+        Initializes the RAGSystem with the given parameters.
+
+        Args:
+            persist_directory_dir (str): Directory to persist the vector store.
+            batch_size (int): Number of documents to process in each batch.
+            top_k_documents (int): Number of top documents to retrieve.
+        """
+        self.top_k_documents = top_k_documents
+        self.llm = self._get_llm()
+        self.chain: Optional[BaseConversationalRetrievalChain] = None
+        self.vector_store_management = VectorStoreManager(
+            persist_directory_dir, batch_size
+        )
+
+    def _get_llm(self):
+        """
+        Retrieves the language model for the RAG system.
+
+        Returns:
+            The language model.
+        """
+        return get_llm_model_chat(temperature=0.1, max_tokens=1000)
+
+    def load_documents(self) -> List:
+        """
+        Loads and splits documents from the specified directory.
+
+        Returns:
+            List: List of loaded documents.
+        """
+        return self.vector_store_management.load_and_process_documents()
+
+    def initialize_vector_store(self, documents: List = None):
+        """
+        Initializes or loads the vector store.
+
+        Args:
+            documents (List, optional): List of documents to initialize the vector store. Defaults to None.
+        """
+        self.vector_store_management.initialize_vector_store(documents)
+
+    def setup_rag_chain(self):
+        """
+        Sets up the RAG chain for document retrieval and question answering.
+        """
+        if self.chain is not None:
+            return
+        retriever = self.vector_store_management.create_retriever(
+            self.llm, self.top_k_documents, bm25_portion=0.03
+        )
+
+        # Contextualize question
+        history_aware_retriever = create_history_aware_retriever(
+            self.llm, retriever, CONTEXTUEL_QUERY_PROMPT
+        )
+        question_answer_chain = create_stuff_documents_chain(self.llm, CHAT_PROMPT)
+        self.chain = create_retrieval_chain(
+            history_aware_retriever, question_answer_chain
+        )
+        logging.info("RAG chain setup complete" + str(self.chain))
+        return self.chain
+
+    def query(self, question: str, history: list = []):
+        """
+        Queries the RAG system with a question and chat history.
+
+        Args:
+            question (str): The question to query.
+            history (list, optional): The chat history. Defaults to [].
+
+        Yields:
+            str: The answer from the RAG system.
+        """
+        if not self.vector_store_management.vs_initialized:
+            self.initialize_vector_store()
+
+        self.setup_rag_chain()
+
+        for token in self.chain.stream({"input": question, "chat_history": history}):
+            if "answer" in token:
+                yield token["answer"]

src/utilities/embedding.py

@@ -0,0 +1,127 @@
+import logging
+import os
+from typing import Any, List
+
+import torch
+from langchain_core.embeddings import Embeddings
+from langchain_huggingface import (
+    HuggingFaceEmbeddings,
+    HuggingFaceEndpointEmbeddings,
+)
+from pydantic import BaseModel, Field
+
+
+class CustomEmbedding(BaseModel, Embeddings):
+    """
+    Custom embedding class that supports both hosted and CPU embeddings.
+    """
+
+    hosted_embedding: HuggingFaceEndpointEmbeddings = Field(
+        default_factory=lambda: None
+    )
+    cpu_embedding: HuggingFaceEmbeddings = Field(default_factory=lambda: None)
+    matryoshka_dim: int = Field(default=256)
+
+    def get_instruction(self) -> str:
+        """
+        Generates the instruction for the embedding model based on environment variables.
+
+        Returns:
+            str: The instruction string.
+        """
+        if "nomic" in os.getenv("HF_MODEL"):
+            return (
+                "search_query: "
+                if (os.getenv("IS_APP", "0") == "1")
+                else "search_document: "
+            )
+        return (
+            "Represent this sentence for searching relevant passages:"
+            if (os.getenv("IS_APP", "0") == "1")
+            else ""
+        )
+
+    def get_hf_embedd(self) -> HuggingFaceEmbeddings:
+        """
+        Initializes the HuggingFaceEmbeddings with the appropriate settings.
+
+        Returns:
+            HuggingFaceEmbeddings: The initialized HuggingFaceEmbeddings object.
+        """
+        return HuggingFaceEmbeddings(
+            model_name=os.getenv("HF_MODEL"),  # You can replace with any HF model
+            model_kwargs={
+                "device": "cpu" if not torch.cuda.is_available() else "cuda",
+                "trust_remote_code": True,
+            },
+            encode_kwargs={
+                "normalize_embeddings": True,
+                "prompt": self.get_instruction(),
+            },
+        )
+
+    def __init__(self, matryoshka_dim=256, **kwargs: Any):
+        """
+        Initializes the CustomEmbedding with the given parameters.
+
+        Args:
+            matryoshka_dim (int): Dimension of the embeddings.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(**kwargs)
+        query_instruction = self.get_instruction()
+        self.matryoshka_dim = matryoshka_dim
+        if torch.cuda.is_available():
+            logging.info("CUDA is available")
+            self.hosted_embedding = self.get_hf_embedd()
+            self.cpu_embedding = self.hosted_embedding
+        else:
+            logging.info("CUDA is not available")
+            self.hosted_embedding = HuggingFaceEndpointEmbeddings(
+                model=os.getenv("HF_MODEL"),
+                model_kwargs={
+                    "encode_kwargs": {
+                        "normalize_embeddings": True,
+                        "prompt": query_instruction,
+                    }
+                },
+                huggingfacehub_api_token=os.getenv("HUGGINGFACEHUB_API_TOKEN"),
+            )
+            self.cpu_embedding = self.get_hf_embedd()
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        """
+        Embeds a list of documents using the appropriate embedding model.
+
+        Args:
+            texts (List[str]): List of document texts to embed.
+
+        Returns:
+            List[List[float]]: List of embedded document vectors.
+        """
+        try:
+            embed = self.hosted_embedding.embed_documents(texts)
+        except Exception as e:
+            logging.warning(f"Issue with batch hosted embedding, moving to CPU: {e}")
+            embed = self.cpu_embedding.embed_documents(texts)
+        return (
+            [e[: self.matryoshka_dim] for e in embed] if self.matryoshka_dim else embed
+        )
+
+    def embed_query(self, text: str) -> List[float]:
+        """
+        Embeds a single query using the appropriate embedding model.
+
+        Args:
+            text (str): The query text to embed.
+
+        Returns:
+            List[float]: The embedded query vector.
+        """
+        try:
+            embed = self.hosted_embedding.embed_query(text)
+        except Exception as e:
+            logging.warning(f"Issue with hosted embedding, moving to CPU: {e}")
+            embed = self.cpu_embedding.embed_query(text)
+        logging.warning(text)
+        return embed[: self.matryoshka_dim] if self.matryoshka_dim else embed

src/utilities/llm_models.py

@@ -0,0 +1,46 @@
+import os
+from enum import Enum
+
+from langchain_groq import ChatGroq
+from langchain_ollama import ChatOllama, OllamaEmbeddings
+
+from .embedding import CustomEmbedding
+
+
+class LLMModel(Enum):
+    OLLAMA = "ChatOllama"
+    GROQ = "ChatGroq"
+
+
+def get_llm_model_chat(temperature=0.01, max_tokens: int = None):
+    if str(os.getenv("USE_OLLAMA_CHAT")) == "1":
+        return ChatOllama(
+            model=os.getenv("OLLAMA_MODEL"),
+            temperature=temperature,
+            num_predict=max_tokens,
+        )
+    return ChatGroq(
+        model=os.getenv("GROQ_MODEL_NAME"),
+        temperature=temperature,
+        max_tokens=max_tokens,
+    )
+
+
+def get_llm_model_embedding():
+    if str(os.getenv("USE_HF_EMBEDDING")) == "1":
+        return CustomEmbedding()
+    return OllamaEmbeddings(
+        model=os.getenv("OLLAM_EMB"),
+        base_url=(
+            os.getenv("OLLAMA_HOST") if os.getenv("OLLAMA_HOST") is not None else None
+        ),
+        client_kwargs=(
+            {
+                "headers": {
+                    "Authorization": "Bearer " + (os.getenv("OLLAMA_TOKEN") or "")
+                }
+            }
+            if os.getenv("OLLAMA_HOST") is not None
+            else None
+        ),
+    )

src/vector_store/document_loader.py

@@ -0,0 +1,163 @@
+import json
+import os
+from glob import glob
+from typing import Dict, List
+
+import tiktoken
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_core.documents import Document
+
+
+def load_qa_dataset(file_path: str) -> List[List[str]]:
+    """
+    Load question-answer dataset from a JSON file.
+
+    Args:
+        file_path (str): Path to the JSON file containing the QA dataset.
+
+    Returns:
+        List[List[str]]: List of questions and their corresponding file names.
+    """
+    raw: Dict[str, List[Dict[str, str]]] = json.load(open(file_path))
+    questions = [
+        [example["response"], os.path.basename(path)]
+        for path, fqa in raw.items()
+        for example in fqa
+    ]
+    return questions
+
+
+def load_summaries(
+    folder_path: str, chunk_size=512, chunk_overlap=100
+) -> List[List[str]]:
+    """
+    Load summaries from text files in a folder and split them into chunks.
+
+    Args:
+        folder_path (str): Path to the folder containing text files.
+        chunk_size (int, optional): Size of each chunk. Defaults to 512.
+        chunk_overlap (int, optional): Overlap between chunks. Defaults to 100.
+
+    Returns:
+        List[List[str]]: List of text chunks and their corresponding folder names.
+    """
+    encoding = tiktoken.get_encoding("cl100k_base")
+    text_splitter = RecursiveCharacterTextSplitter(
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        length_function=lambda x: len(encoding.encode(x)),
+    )
+
+    files = sorted(glob(os.path.join(folder_path, "**/*.txt"), recursive=True))
+    grouped_files: Dict[str, List[str]] = {}
+    for file in files:
+        folder = os.path.dirname(file)
+        grouped_files.setdefault(folder, []).append(file)
+
+    summaries = []
+    for folder, file_list in grouped_files.items():
+        content = "\n\n".join(open(file).read() for file in file_list)
+        summaries.extend((chunk, folder) for chunk in text_splitter.split_text(content))
+
+    return summaries
+
+
+def load_pages_from_folder(
+    folder_path: str, chunk_size=512, chunk_overlap=100
+) -> List[List[str]]:
+    """
+    Load pages from text files in a folder and split them into chunks.
+
+    Args:
+        folder_path (str): Path to the folder containing text files.
+        chunk_size (int, optional): Size of each chunk. Defaults to 512.
+        chunk_overlap (int, optional): Overlap between chunks. Defaults to 100.
+
+    Returns:
+        List[List[str]]: List of text chunks and their corresponding folder names.
+    """
+    files = sorted(glob(os.path.join(folder_path, "*.txt")))
+    name = os.path.basename(folder_path)
+    pages = [open(path).read().strip() for path in files]
+    content = "\n\n".join(pages)
+    encoding = tiktoken.get_encoding("cl100k_base")
+    text_splitter = RecursiveCharacterTextSplitter(
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        length_function=lambda x: len(encoding.encode(x)),
+    )
+    summaries = text_splitter.split_text(content)
+    return [(i, name) for i in summaries]
+
+
+def load_pages_from_folders(
+    folders_path: List[str], chunk_size=512, chunk_overlap=100
+) -> List[List[str]]:
+    """
+    Load pages from multiple folders and split them into chunks.
+
+    Args:
+        folders_path (List[str]): List of folder paths containing text files.
+        chunk_size (int, optional): Size of each chunk. Defaults to 512.
+        chunk_overlap (int, optional): Overlap between chunks. Defaults to 100.
+
+    Returns:
+        List[List[str]]: List of text chunks and their corresponding folder names.
+    """
+    data = sum(
+        [
+            load_pages_from_folder(folder, chunk_size, chunk_overlap)
+            for folder in folders_path
+        ],
+        start=[],
+    )
+    return data
+
+
+def load_dataset(language="fr") -> List[Document]:
+    """
+    Load the entire dataset including questions, summaries, and pages.
+
+    Args:
+        language (str, optional): Language of the dataset. Defaults to "fr".
+
+    Returns:
+        List[Document]: List of Document objects containing the dataset.
+    """
+    question_path = f"saved_summaries/question_{language}.json"
+    questions = load_qa_dataset(question_path)
+
+    summary_path = "data/summaries/summaries_" + language
+    summaries = load_summaries(
+        summary_path,
+        chunk_size=512,
+        chunk_overlap=100,
+    )
+
+    pages = load_pages_from_folders(
+        ["data/pages/297054", "data/pages/297054_Volume_2"],
+        chunk_size=512,
+        chunk_overlap=100,
+    )
+
+    documents = questions + summaries + pages
+    documents = [
+        Document(page_content=doc, metadata={"source": source})
+        for (doc, source) in documents
+    ]
+    return documents
+
+
+class DocumentLoader:
+    """
+    Handles loading and splitting documents from directories.
+    """
+
+    def load_documents(self) -> List[Document]:
+        """
+        Determines and loads documents based on file type.
+
+        Returns:
+            List[Document]: List of Document objects containing the dataset.
+        """
+        return load_dataset()

src/vector_store/prompts.py

@@ -0,0 +1,24 @@
+from langchain_core.prompts.prompt import PromptTemplate
+
+DEFAULT_QUERY_PROMPT = PromptTemplate(
+    input_variables=["question"],
+    template="""You are an AI language model assistant tasked with generating alternative versions of a given user question. Your goal is to create 3 different perspectives on the original question to help retrieve relevant documents from a vector database. This approach aims to overcome some limitations of distance-based similarity search.
+
+When generating alternative questions, follow these guidelines:
+1. Maintain the core intent of the original question
+2. Use different phrasing, synonyms, or sentence structures
+3. Consider potential related aspects or implications of the question
+4. Avoid introducing new topics or drastically changing the subject matter
+
+Here is the original question:
+
+{question}
+
+
+Generate 3 alternative versions of this question. Provide your output as a numbered list, with each alternative question on a new line. Do not include any additional explanation or commentary.
+
+Remember, the purpose of these alternative questions is to broaden the search scope while staying relevant to the user's original intent. This will help in retrieving a diverse set of potentially relevant documents from the vector database.
+
+Do not include any additional explanation or commentary, just give 3 alternative questions.
+""",
+)

src/vector_store/vector_store.py

@@ -0,0 +1,115 @@
+import os
+from typing import Dict, List
+
+from langchain.retrievers import MultiQueryRetriever
+from langchain_chroma import Chroma
+from langchain_core.documents import Document
+from tqdm import tqdm
+
+from ..utilities.llm_models import get_llm_model_embedding
+from .document_loader import DocumentLoader
+from .prompts import DEFAULT_QUERY_PROMPT
+
+
+def get_collection_name() -> str:
+    """
+    Derives the collection name from an environment variable.
+
+    Returns:
+        str: Processed collection name.
+    """
+    return os.getenv("HF_MODEL", "default_model").split(":")[0].split("/")[-1]
+
+
+class VectorStoreManager:
+    """
+    Manages vector store initialization, updates, and retrieval.
+    """
+
+    def __init__(self, persist_directory: str, batch_size: int = 64):
+        """
+        Initializes the VectorStoreManager with the given parameters.
+
+        Args:
+            persist_directory (str): Directory to persist the vector store.
+            batch_size (int): Number of documents to process in each batch.
+        """
+        self.persist_directory = persist_directory
+        self.batch_size = batch_size
+        self.embeddings = get_llm_model_embedding()
+        self.collection_name = get_collection_name()
+        self.vector_stores: Dict[str, Chroma] = {"chroma": None}
+        self.vs_initialized = False
+
+    def _batch_process_documents(self, documents: List[Document]):
+        """
+        Processes documents in batches for vector store initialization.
+
+        Args:
+            documents (List[Document]): List of documents to process.
+        """
+        for i in tqdm(
+            range(0, len(documents), self.batch_size), desc="Processing documents"
+        ):
+            batch = documents[i : i + self.batch_size]
+            if not self.vs_initialized:
+                self.vector_stores["chroma"] = Chroma.from_documents(
+                    collection_name=self.collection_name,
+                    documents=batch,
+                    embedding=self.embeddings,
+                    persist_directory=self.persist_directory,
+                )
+                self.vs_initialized = True
+            else:
+                self.vector_stores["chroma"].add_documents(batch)
+
+    def initialize_vector_store(self, documents: List[Document] = None):
+        """
+        Initializes or loads the vector store.
+
+        Args:
+            documents (List[Document], optional): List of documents to initialize the vector store with.
+        """
+        if documents:
+            self._batch_process_documents(documents)
+        else:
+            self.vector_stores["chroma"] = Chroma(
+                collection_name=self.collection_name,
+                persist_directory=self.persist_directory,
+                embedding_function=self.embeddings,
+            )
+        self.vs_initialized = True
+
+    def create_retriever(
+        self, llm, n_documents: int, bm25_portion: float = 0.8
+    ) -> MultiQueryRetriever:
+        """
+        Creates a retriever using Chroma.
+
+        Args:
+            llm: Language model to use for the retriever.
+            n_documents (int): Number of documents to retrieve.
+            bm25_portion (float): Portion of BM25 to use in the retriever.
+
+        Returns:
+            MultiQueryRetriever: Configured retriever.
+        """
+        self.vector_store = MultiQueryRetriever.from_llm(
+            retriever=self.vector_stores["chroma"].as_retriever(
+                search_kwargs={"k": n_documents}
+            ),
+            llm=llm,
+            include_original=True,
+            prompt=DEFAULT_QUERY_PROMPT
+        )
+        return self.vector_store
+
+    def load_and_process_documents(self) -> List[Document]:
+        """
+        Loads and processes documents from the specified directory.
+
+        Returns:
+            List[Document]: List of processed documents.
+        """
+        loader = DocumentLoader()
+        return loader.load_documents()