Add ImageGather.jl as a second RAG corpus, portability fixes, and unit tests

CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Unreleased
+
+### Added
+- **ImageGather.jl as a second retrieval corpus.** The agent can now ground
+  generated Julia in ImageGather.jl alongside JUDI.jl.
+  - Cloned `slimgroup/ImageGather.jl@ext_PhyParams` into
+    `src/judiagent/rag/imagegather/` and trimmed it to the material needed
+    for retrieval and attribution: `docs/src/*.md`, `examples/*.jl`, the
+    upstream `LICENSE`, and the upstream `README.md` (which links to the
+    upstream repo for the figures, notebooks, source code, and tests that
+    were dropped from this snapshot).
+  - Registered `imagegather/docs` (markdown) and `imagegather/examples`
+    (Julia) in `RAG_CATALOG` (`src/judiagent/rag/catalog.py`), reusing the
+    existing markdown and Julia-example chunkers.
+  - New retrieval tool `search_imagegather_examples`
+    (`src/judiagent/tools/retrieve.py`) built via the shared
+    `_build_retrieval_tool` factory; wired into the iterative agent
+    (`src/judiagent/agents/agent.py`), the autonomous ReAct agent
+    (`src/judiagent/agents/autonomous_agent.py`), and the `tools` package
+    `__init__`.
+  - Updated `GATHER_INTELLIGENCE` in `src/judiagent/prompting/shared.py` to
+    tell the model when to pick `search_imagegather_examples` over
+    `search_judi_examples`.
+
+### Changed
+- `search_codebase` (`src/judiagent/tools/retrieve.py`) now greps both
+  `rag/judi/` and `rag/imagegather/` in a single invocation. Tool description
+  updated to reflect the broader scope.
+- `src/judiagent/rag/THIRD_PARTY.md` now documents the ImageGather corpus
+  alongside JUDI (repo, branch `ext_PhyParams`, MIT license, maintainer,
+  citation pointers).
+- ImageGather example scripts (`examples/layers_cig.jl`,
+  `examples/layers_sscig.jl`, `examples/offset_map.jl`) annotated with
+  JUDI-style `# # Heading` section markers so the Julia example chunker
+  produces ~19 well-titled chunks instead of three whole-file blobs. Code
+  itself is unchanged; only top-level prose lines were inserted between
+  logical sections.
+
+### Operational notes
+- After pulling this change, delete any stale per-source caches so the index
+  rebuilds with the new corpus on the next agent run:
+  ```bash
+  rm -f  src/judiagent/rag/loaded_store/loaded_judi_*.pkl \
+         src/judiagent/rag/loaded_store/loaded_imagegather_*.pkl
+  rm -rf src/judiagent/rag/retriever_store/retriever_judi_* \
+         src/judiagent/rag/retriever_store/retriever_imagegather_*
+  ```
+  Do not remove the `__init__.py` files in those directories — they are
+  package markers, not data.

pyproject.toml

@@ -22,7 +22,6 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
-    "Programming Language :: Julia",
     "Topic :: Scientific/Engineering",
 ]
 dependencies = [

src/judiagent/agents/agent.py

@@ -35,6 +35,7 @@
     lookup_function_docs,
     read_from_file,
     search_codebase,
+    search_imagegather_examples,
     search_judi_examples,
     write_to_file,
 )
@@ -233,6 +234,7 @@ def _handle_validation_result(
         search_codebase,
         lookup_function_docs,
         search_judi_examples,
+        search_imagegather_examples,
     ],
     stream_output=True,
 )

src/judiagent/agents/autonomous_agent.py

@@ -33,6 +33,7 @@
     lookup_function_docs,
     read_from_file,
     search_codebase,
+    search_imagegather_examples,
     search_judi_examples,
     write_to_file,
 )
@@ -169,6 +170,7 @@ def generate_response(self, state: AgentState, config: RunnableConfig) -> dict:
         search_codebase,
         lookup_function_docs,
         search_judi_examples,
+        search_imagegather_examples,
     ],
     stream_output=True,
 )

src/judiagent/prompting/shared.py

@@ -38,7 +38,8 @@
 
 Always retrieve JUDI.jl examples before generating code.
 
-- Use `search_judi_examples` first for JUDI workflows and API patterns.
+- Use `search_judi_examples` for JUDI.jl workflows and API patterns.
+- Use `search_imagegather_examples` for ImageGather.jl workflows (surface and subsurface common-image gathers, extended Born modeling, extended physical parameters).
 - Use `lookup_function_docs` for specific signatures and function behavior.
 - Use `search_codebase`, `list_files_in_directory`, and `read_from_file` to collect surrounding context.
 - If code fails, retrieve more context before trying another fix.

src/judiagent/rag/THIRD_PARTY.md

@@ -1,8 +1,9 @@
 # Third-Party Retrieval Corpora
 
-`src/judiagent/rag/judi/` is retrieval material, not original JUDIAgent agent
-implementation code. It is included so the agent can ground generated Julia in
-real JUDI.jl documentation and example workflows.
+`src/judiagent/rag/judi/` and `src/judiagent/rag/imagegather/` are retrieval
+material, not original JUDIAgent agent implementation code. They are included
+so the agent can ground generated Julia in real upstream documentation and
+example workflows.
 
 ## JUDI.jl Material
 
@@ -20,6 +21,29 @@ Some examples contain additional author notes, publication references, and
 dataset instructions. Keep those notices with the files when redistributing or
 modifying the corpus.
 
+## ImageGather.jl Material
+
+The ImageGather documentation and examples originate from the ImageGather.jl
+project:
+
+- Repository: <https://github.com/slimgroup/ImageGather.jl>
+- Branch: `ext_PhyParams` (extended physical parameters / extended Born
+  modeling for subsurface offset common-image gathers).
+- License: MIT, copyright (c) 2020 SLIM group @ Georgia Institute of
+  Technology. The upstream MIT license text is included in
+  `src/judiagent/rag/imagegather/LICENSE`.
+- Maintainer / citation contact: Mathias Louboutin
+  (<mlouboutin3@gatech.edu>). See `src/judiagent/rag/imagegather/README.md`
+  for the referenced method papers (Giboli et al., SEG 2012; Dafni & Symes,
+  GJI 2019) and the Zenodo DOI badge for software citation.
+
+The vendored snapshot is trimmed to the material needed for retrieval and
+attribution: `docs/src/*.md`, `examples/*.jl`, the upstream `LICENSE`, and
+`README.md` (which links to the upstream repository for the figures,
+notebooks, source code, and tests that were dropped from this snapshot). The
+`imagegather` catalog entries only index `.md` files under `docs/src/` and
+`.jl` files under `examples/`.
+
 ## Distribution Notes
 
 The Python package build excludes bulky notebook outputs and binary example data

src/judiagent/rag/catalog.py

@@ -59,4 +59,39 @@ class CorpusSpec:
             ),
         ),
     },
+    "imagegather": {
+        "docs": CorpusSpec(
+            source_dir=str(PROJECT_ROOT / "rag" / "imagegather" / "docs" / "src"),
+            persist_dir=lambda embedding_family: str(
+                PROJECT_ROOT
+                / "rag"
+                / "retriever_store"
+                / f"retriever_imagegather_docs_{embedding_family}"
+            ),
+            cache_file=str(
+                PROJECT_ROOT / "rag" / "loaded_store" / "loaded_imagegather_docs.pkl"
+            ),
+            collection_name="imagegather_docs",
+            filetypes=("md",),
+            chunk_document=split_markdown_document,
+        ),
+        "examples": CorpusSpec(
+            source_dir=str(PROJECT_ROOT / "rag" / "imagegather" / "examples"),
+            persist_dir=lambda embedding_family: str(
+                PROJECT_ROOT
+                / "rag"
+                / "retriever_store"
+                / f"retriever_imagegather_examples_{embedding_family}"
+            ),
+            cache_file=str(
+                PROJECT_ROOT / "rag" / "loaded_store" / "loaded_imagegather_examples.pkl"
+            ),
+            collection_name="imagegather_examples",
+            filetypes=("jl",),
+            chunk_document=partial(
+                split_julia_example_document,
+                header_to_split_on=1,
+            ),
+        ),
+    },
 }

src/judiagent/rag/imagegather/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 SLIM group @ Georgia Institute of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/judiagent/rag/imagegather/README.md

@@ -0,0 +1,38 @@
+
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://slimgroup.github.io/ImageGather.jl/dev) 
+[![DOI](https://zenodo.org/badge/376881077.svg)](https://zenodo.org/badge/latestdoi/376881077)
+
+# ImageGather.jl
+
+This package implements image gather functions for seismic inversion and QC. We currently offer surface gathers via the double RTM method and subsurface offset image gather. The subsurface offset common image gather are implemented via the extended born modeling operator and its adjoint allowing for extended LSRTM.
+
+# Example
+
+A simple example of a surface image gather for a layered model can be found in `examples/layers_cig.jl`. This example produces the following image gathers:
+
+![Single CDP offset gather](./docs/img/cig_cdp.png)
+: Offset gather for a good and bad background velocity model at a different position along X.
+
+This first plot shows the expected behavior with respect to the offset. We clearly see the flat events with a correct velocity while we obtain the predicted upwards and downwards parabolic events for a respectively low and high velocity at large offset.
+
+![Seismic line of offset gathers](./docs/img/cig_line.png)
+: Stack of offset gather along the X direction showing the difference in flatness and alignment for a good and bad background velocity model.
+
+This second plot shows the stack along X of different gathers that shows the focusing onto the reflectors with a correct velocity while the high and low-velocity models produce unfocused and misplaced events.
+
+
+# Contributions
+
+Contributions are welcome.
+
+# References
+
+This work is inspired by the original [double RTM](https://library.seg.org/doi/pdfplus/10.1190/segam2012-1007.1) paper for the surface gather and the [Extended Born]() paper for extended jacobian for subsurface gathers.
+
+- Matteo Giboli, Reda Baina, Laurence Nicoletis, and Bertrand Duquet, "Reverse Time Migration surface offset gathers part 1: a new method to produce ‘classical’ common image gathers", SEG Technical Program Expanded Abstracts 2012.
+- Raanan Dafni, William W Symes, "Generalized reflection tomography formulation based on subsurface offset extended imaging",
+Geophysical Journal International, Volume 216, Issue 2, February 2019, Pages 1025–1042, https://doi.org/10.1093/gji/ggy478
+
+# Authors
+
+This package is developed and maintained by Mathias Louboutin <mlouboutin3@gatech.edu>

src/judiagent/rag/imagegather/docs/src/index.md

@@ -0,0 +1,33 @@
+# ImageGather.jl documentation
+
+ImageGather.jl provides computational QC tools for wave-equation based inversion. Namely we provides two main widely used workflows:
+
+- Surface offset gathers (also called surface common image gather). Surface gather compute images of (RTMs) for different offset to verify the accuracy of the background velocity. The method we implement here is based on the double-rtm method [Giboli](@cite) that allows the computation of the gather with two RTMs only instead of one per offset (or offset bin).
+- Subsurface offset gathers (also called subsurface common image gather) [sscig](@cite).
+
+## Surface offset gathers
+
+```@docs
+surface_gather
+double_rtm_cig
+```
+
+## Subsurface offset gathers
+
+```@docs
+judiExtendedJacobian
+```
+
+## Utility functions
+
+```@autodocs
+Modules = [ImageGather]
+Pages = ["utils.jl"]
+```
+
+# References
+
+```@bibliography
+```
+
+