decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/mcp_server/legal/core/courtlistener_store.py

@@ -0,0 +1,762 @@
+"""
+CourtListener Data Store — Local mock of CourtListener API v4.3.
+
+Loads data fetched from CourtListener REST API and provides methods
+that mirror each endpoint's behavior (filtering, pagination, lookup).
+
+All list endpoints return paginated format:
+    {"count": N, "next": null, "previous": null, "results": [...]}
+
+All detail endpoints return the object directly (or {"detail": "Not found."} on 404).
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class CourtListenerStore:
+    """Local mock of CourtListener API v4.3 data store."""
+
+    def __init__(self, data_dir: str):
+        self.data_dir = Path(data_dir) / "courtlistener"
+
+        # Core data stores (keyed by ID)
+        self._clusters: Dict[int, dict] = {}
+        self._opinions: Dict[int, dict] = {}
+        self._courts: Dict[str, dict] = {}
+        self._dockets: Dict[int, dict] = {}
+        self._docket_entries: Dict[int, dict] = {}
+        self._recap_documents: Dict[int, dict] = {}
+        self._audio: Dict[int, dict] = {}
+
+        # People / Judges
+        self._people: Dict[int, dict] = {}
+        self._positions: Dict[int, dict] = {}
+        self._educations: Dict[int, dict] = {}
+        self._political_affiliations: Dict[int, dict] = {}
+        self._aba_ratings: Dict[int, dict] = {}
+
+        # Parties / Attorneys
+        self._parties: Dict[int, dict] = {}
+        self._attorneys: Dict[int, dict] = {}
+
+        # Financial Disclosures
+        self._financial_disclosures: Dict[int, dict] = {}
+        self._investments: Dict[int, dict] = {}
+        self._gifts: Dict[int, dict] = {}
+        self._debts: Dict[int, dict] = {}
+        self._agreements: Dict[int, dict] = {}
+        self._non_investment_incomes: Dict[int, dict] = {}
+        self._disclosure_positions: Dict[int, dict] = {}
+        self._reimbursements: Dict[int, dict] = {}
+        self._spouse_incomes: Dict[int, dict] = {}
+
+        # Other
+        self._bankruptcy_info: Dict[int, dict] = {}
+        self._originating_court_info: Dict[int, dict] = {}
+        self._fjc_data: Dict[int, dict] = {}
+
+        # Opinions-cited relationships
+        self._opinions_cited: List[dict] = []
+
+        # Search index: query_slug -> raw search response
+        self._search_cache: Dict[str, dict] = {}
+
+        self._load_all()
+
+    # ==================================================================
+    # DATA LOADING
+    # ==================================================================
+
+    def _load_all(self):
+        """Load all data from JSON files."""
+        if not self.data_dir.exists():
+            print(f"[CourtListenerStore] Data dir not found: {self.data_dir}")
+            return
+
+        self._load_search_cache()
+        self._load_clusters()
+        self._load_opinions()
+        self._load_courts()
+        self._load_people()
+        self._load_dockets()
+        self._load_financial_disclosures()
+        self._load_audio()
+        self._load_other()
+        self._load_opinions_cited()
+
+    def _load_json_file(self, filename: str) -> Any:
+        """Load a JSON file from the data directory."""
+        filepath = self.data_dir / filename
+        if not filepath.exists():
+            return []
+        try:
+            with open(filepath) as f:
+                return json.load(f)
+        except Exception as e:
+            print(f"[CourtListenerStore] Error loading {filepath}: {e}")
+            return []
+
+    def _load_json_dir(self, dirname: str) -> Dict[int, dict]:
+        """Load all JSON files from a subdirectory, keyed by filename (ID)."""
+        dirpath = self.data_dir / dirname
+        result = {}
+        if not dirpath.exists():
+            return result
+        for filepath in dirpath.glob("*.json"):
+            try:
+                with open(filepath) as f:
+                    data = json.load(f)
+                key = filepath.stem
+                if key.isdigit():
+                    key = int(key)
+                result[key] = data
+            except Exception as e:
+                print(f"[CourtListenerStore] Error loading {filepath}: {e}")
+        return result
+
+    def _load_list_to_dict(self, filename: str, key_field: str = "id") -> dict:
+        """Load a JSON list file and index by a key field."""
+        data = self._load_json_file(filename)
+        if not isinstance(data, list):
+            return {}
+        result = {}
+        for item in data:
+            k = item.get(key_field)
+            if k is not None:
+                result[k] = item
+        return result
+
+    def _load_search_cache(self):
+        """Load search result files."""
+        search_dir = self.data_dir / "search_results"
+        if not search_dir.exists():
+            return
+        for filepath in search_dir.glob("*.json"):
+            slug = filepath.stem
+            try:
+                with open(filepath) as f:
+                    self._search_cache[slug] = json.load(f)
+            except Exception:
+                pass
+
+    def _load_clusters(self):
+        self._clusters = self._load_json_dir("clusters")
+
+    def _load_opinions(self):
+        self._opinions = self._load_json_dir("opinions")
+
+    def _load_courts(self):
+        data = self._load_json_file("courts.json")
+        if isinstance(data, list):
+            for court in data:
+                cid = court.get("id")
+                if cid:
+                    self._courts[cid] = court
+
+    def _load_people(self):
+        self._people = self._load_list_to_dict("people.json")
+        self._positions = self._load_list_to_dict("positions.json")
+        self._educations = self._load_list_to_dict("educations.json")
+        self._political_affiliations = self._load_list_to_dict("political_affiliations.json")
+        self._aba_ratings = self._load_list_to_dict("aba_ratings.json")
+
+    def _load_dockets(self):
+        self._dockets = self._load_list_to_dict("dockets.json")
+        self._docket_entries = self._load_list_to_dict("docket_entries.json")
+        self._parties = self._load_list_to_dict("parties.json")
+        self._attorneys = self._load_list_to_dict("attorneys.json")
+
+    def _load_financial_disclosures(self):
+        self._financial_disclosures = self._load_list_to_dict("financial_disclosures.json")
+        self._investments = self._load_list_to_dict("investments.json")
+        self._gifts = self._load_list_to_dict("gifts.json")
+        self._debts = self._load_list_to_dict("debts.json")
+        self._agreements = self._load_list_to_dict("agreements.json")
+        self._non_investment_incomes = self._load_list_to_dict("non_investment_incomes.json")
+        self._disclosure_positions = self._load_list_to_dict("disclosure_positions.json")
+        self._reimbursements = self._load_list_to_dict("reimbursements.json")
+        self._spouse_incomes = self._load_list_to_dict("spouse_incomes.json")
+
+    def _load_audio(self):
+        self._audio = self._load_list_to_dict("audio.json")
+
+    def _load_other(self):
+        self._bankruptcy_info = self._load_list_to_dict("bankruptcy_info.json")
+        self._originating_court_info = self._load_list_to_dict("originating_court_info.json")
+        self._fjc_data = self._load_list_to_dict("fjc_data.json")
+        self._recap_documents = self._load_list_to_dict("recap_documents.json")
+
+    def _load_opinions_cited(self):
+        data = self._load_json_file("opinions_cited.json")
+        if isinstance(data, list):
+            self._opinions_cited = data
+
+    # ==================================================================
+    # HELPERS
+    # ==================================================================
+
+    @staticmethod
+    def _paginate(items: list, page_size: int = 20, cursor: str = "") -> dict:
+        """Return paginated response format."""
+        # Simple offset-based pagination
+        offset = 0
+        if cursor:
+            try:
+                offset = int(cursor)
+            except ValueError:
+                offset = 0
+
+        total = len(items)
+        page_items = items[offset:offset + page_size]
+        next_cursor = None
+        if offset + page_size < total:
+            next_cursor = str(offset + page_size)
+
+        return {
+            "count": total,
+            "next": next_cursor,
+            "previous": str(max(0, offset - page_size)) if offset > 0 else None,
+            "results": page_items,
+        }
+
+    @staticmethod
+    def _extract_id_from_url(ref) -> int:
+        """Extract numeric ID from a CL API URL string or nested object dict."""
+        if not ref:
+            return 0
+        # If it's a dict (nested object), extract the 'id' field
+        if isinstance(ref, dict):
+            return int(ref.get("id", 0))
+        # If it's an int already
+        if isinstance(ref, int):
+            return ref
+        # Otherwise treat as URL string
+        url = str(ref)
+        parts = url.rstrip("/").split("/")
+        for part in reversed(parts):
+            if part.isdigit():
+                return int(part)
+        return 0
+
+    def _text_match(self, text: str, query: str) -> bool:
+        """Simple text matching for search."""
+        if not query:
+            return True
+        query_lower = query.lower()
+        words = query_lower.split()
+        text_lower = text.lower()
+        return any(w in text_lower for w in words)
+
+    # ==================================================================
+    # UNIFIED SEARCH (mirrors GET /search/)
+    # ==================================================================
+
+    def search(self, q: str, type: str = "o", court: str = "",
+               date_filed_after: str = "", date_filed_before: str = "",
+               page_size: int = 20, cursor: str = "",
+               order_by: str = "score desc") -> dict:
+        """Unified search across case law, RECAP, judges, oral arguments.
+
+        type: o (opinions), r (RECAP), rd (RECAP documents), d (dockets), p (people), oa (oral arguments)
+        """
+        if type == "o":
+            return self._search_opinions(q, court, date_filed_after, date_filed_before, page_size, cursor)
+        elif type == "d":
+            return self._search_dockets_internal(q, court, page_size, cursor)
+        elif type == "p":
+            return self._search_people(q, page_size, cursor)
+        elif type == "oa":
+            return self._search_audio(q, page_size, cursor)
+        elif type in ("r", "rd"):
+            return self._search_recap(q, page_size, cursor)
+        else:
+            return self._search_opinions(q, court, date_filed_after, date_filed_before, page_size, cursor)
+
+    def _search_opinions(self, q: str, court: str = "",
+                         date_filed_after: str = "", date_filed_before: str = "",
+                         page_size: int = 20, cursor: str = "") -> dict:
+        """Search opinions — first check cached search results, then fall back to cluster scan."""
+        # Try to find a cached search result that matches
+        q_slug = q.lower().replace(" ", "_")[:50]
+        if q_slug in self._search_cache:
+            cached = self._search_cache[q_slug]
+            results = cached.get("results", [])
+            # Apply filters
+            if court:
+                results = [r for r in results if court.lower() in str(r.get("court_id", "")).lower()]
+            if date_filed_after:
+                results = [r for r in results if str(r.get("dateFiled", "")) >= date_filed_after]
+            if date_filed_before:
+                results = [r for r in results if str(r.get("dateFiled", "")) <= date_filed_before]
+            return self._paginate(results, page_size, cursor)
+
+        # Fall back to scanning clusters
+        results = []
+        for cid, cluster in self._clusters.items():
+            searchable = " ".join([
+                str(cluster.get("case_name", "")),
+                str(cluster.get("case_name_full", "")),
+                str(cluster.get("syllabus", "")),
+                str(cluster.get("summary", "")),
+                str(cluster.get("judges", "")),
+                str(cluster.get("attorneys", "")),
+                str(cluster.get("nature_of_suit", "")),
+            ])
+
+            if not self._text_match(searchable, q):
+                continue
+
+            if court:
+                # Extract court_id from docket URL or cluster data
+                cluster_court = ""
+                docket_url = cluster.get("docket", "")
+                if isinstance(docket_url, str):
+                    # Try to get court from linked docket
+                    did = self._extract_id_from_url(docket_url)
+                    if did and did in self._dockets:
+                        cluster_court = self._dockets[did].get("court_id", "")
+                if court.lower() not in cluster_court.lower():
+                    continue
+
+            date_filed = str(cluster.get("date_filed", ""))
+            if date_filed_after and date_filed < date_filed_after:
+                continue
+            if date_filed_before and date_filed > date_filed_before:
+                continue
+
+            # Build search result format
+            citations = cluster.get("citations", [])
+            citation_strs = []
+            for c in citations:
+                if isinstance(c, dict):
+                    citation_strs.append(f"{c.get('volume', '')} {c.get('reporter', '')} {c.get('page', '')}".strip())
+                elif isinstance(c, str):
+                    citation_strs.append(c)
+
+            result = {
+                "absolute_url": f"/opinion/{cid}/{cluster.get('slug', '')}/",
+                "caseName": cluster.get("case_name", ""),
+                "caseNameFull": cluster.get("case_name_full", ""),
+                "citation": citation_strs,
+                "citeCount": cluster.get("citation_count", 0),
+                "cluster_id": cid,
+                "court": "",
+                "court_id": "",
+                "dateFiled": date_filed,
+                "docketNumber": "",
+                "docket_id": self._extract_id_from_url(cluster.get("docket", "")),
+                "judge": cluster.get("judges", ""),
+                "snippet": (cluster.get("syllabus", "") or cluster.get("summary", ""))[:300],
+            }
+            results.append(result)
+
+        # If court filter produced no results, retry without court filter
+        if not results and court:
+            return self._search_opinions(q, court="",
+                                          date_filed_after=date_filed_after,
+                                          date_filed_before=date_filed_before,
+                                          page_size=page_size, cursor=cursor)
+
+        # Sort by date descending
+        results.sort(key=lambda x: x.get("dateFiled", ""), reverse=True)
+        return self._paginate(results, page_size, cursor)
+
+    def _search_dockets_internal(self, q: str, court: str = "",
+                                  page_size: int = 20, cursor: str = "") -> dict:
+        """Search dockets."""
+        results = []
+        for did, docket in self._dockets.items():
+            searchable = " ".join([
+                str(docket.get("case_name", "")),
+                str(docket.get("case_name_full", "")),
+                str(docket.get("docket_number", "")),
+                str(docket.get("nature_of_suit", "")),
+            ])
+            if not self._text_match(searchable, q):
+                continue
+            if court and court.lower() not in str(docket.get("court_id", "")).lower():
+                continue
+            results.append(docket)
+
+        results.sort(key=lambda x: str(x.get("date_filed", "")), reverse=True)
+        return self._paginate(results, page_size, cursor)
+
+    def _search_people(self, q: str, page_size: int = 20, cursor: str = "") -> dict:
+        """Search people/judges."""
+        results = []
+        for pid, person in self._people.items():
+            searchable = " ".join([
+                str(person.get("name_first", "")),
+                str(person.get("name_last", "")),
+                str(person.get("name_middle", "")),
+            ])
+            if not self._text_match(searchable, q):
+                continue
+            results.append(person)
+        return self._paginate(results, page_size, cursor)
+
+    def _search_audio(self, q: str, page_size: int = 20, cursor: str = "") -> dict:
+        """Search oral arguments."""
+        results = []
+        for aid, audio in self._audio.items():
+            searchable = " ".join([
+                str(audio.get("case_name", "")),
+                str(audio.get("judges", "")),
+            ])
+            if not self._text_match(searchable, q):
+                continue
+            results.append(audio)
+        return self._paginate(results, page_size, cursor)
+
+    def _search_recap(self, q: str, page_size: int = 20, cursor: str = "") -> dict:
+        """Search RECAP documents."""
+        results = []
+        for rid, doc in self._recap_documents.items():
+            searchable = str(doc.get("description", ""))
+            if not self._text_match(searchable, q):
+                continue
+            results.append(doc)
+        return self._paginate(results, page_size, cursor)
+
+    # ==================================================================
+    # CASE LAW
+    # ==================================================================
+
+    def get_cluster(self, cluster_id: int) -> dict:
+        """Get cluster by ID (mirrors GET /clusters/{id}/)."""
+        cluster = self._clusters.get(cluster_id)
+        if not cluster:
+            return {"detail": "Not found."}
+        return dict(cluster)
+
+    def get_opinion(self, opinion_id: int) -> dict:
+        """Get opinion by ID (mirrors GET /opinions/{id}/)."""
+        opinion = self._opinions.get(opinion_id)
+        if not opinion:
+            return {"detail": "Not found."}
+        return dict(opinion)
+
+    def get_opinions_cited(self, citing_opinion: int = 0, cited_opinion: int = 0,
+                           page_size: int = 20) -> dict:
+        """Get citation relationships (mirrors GET /opinions-cited/)."""
+        results = []
+        for rel in self._opinions_cited:
+            if citing_opinion:
+                citing_url = rel.get("citing_opinion", "")
+                if self._extract_id_from_url(citing_url) != citing_opinion:
+                    continue
+            if cited_opinion:
+                cited_url = rel.get("cited_opinion", "")
+                if self._extract_id_from_url(cited_url) != cited_opinion:
+                    continue
+            results.append(rel)
+        return self._paginate(results, page_size)
+
+    def citation_lookup(self, text: str = "", volume: str = "", reporter: str = "",
+                        page: str = "") -> list:
+        """Resolve citations (mirrors POST /citation-lookup/).
+
+        Returns a list of lookup results.
+        """
+        results = []
+
+        # If text is provided, try to parse citations from it
+        # If volume/reporter/page are provided, look up directly
+        if volume and reporter and page:
+            # Search clusters for matching citation
+            target = f"{volume} {reporter} {page}".strip()
+            for cid, cluster in self._clusters.items():
+                for cit in cluster.get("citations", []):
+                    if isinstance(cit, dict):
+                        cit_str = f"{cit.get('volume', '')} {cit.get('reporter', '')} {cit.get('page', '')}".strip()
+                        if (str(cit.get("volume", "")) == str(volume) and
+                            reporter.lower() in str(cit.get("reporter", "")).lower() and
+                            str(cit.get("page", "")) == str(page)):
+                            results.append({
+                                "citation": cit_str,
+                                "normalized_citations": [cit_str],
+                                "status": 200,
+                                "error_message": "",
+                                "clusters": [cluster],
+                            })
+                            return results
+
+            # Not found
+            results.append({
+                "citation": target,
+                "normalized_citations": [target],
+                "status": 404,
+                "error_message": "Citation not found in database.",
+                "clusters": [],
+            })
+            return results
+
+        if text:
+            # Try to find the text as a citation string in any cluster
+            text_lower = text.lower().strip()
+            for cid, cluster in self._clusters.items():
+                for cit in cluster.get("citations", []):
+                    cit_str = ""
+                    if isinstance(cit, dict):
+                        cit_str = f"{cit.get('volume', '')} {cit.get('reporter', '')} {cit.get('page', '')}".strip()
+                    elif isinstance(cit, str):
+                        cit_str = cit
+
+                    if cit_str and text_lower in cit_str.lower():
+                        results.append({
+                            "citation": cit_str,
+                            "normalized_citations": [cit_str],
+                            "status": 200,
+                            "error_message": "",
+                            "clusters": [cluster],
+                        })
+                        return results
+
+                # Also check case_name
+                if text_lower in cluster.get("case_name", "").lower():
+                    citations = cluster.get("citations", [])
+                    cit_str = ""
+                    if citations:
+                        c = citations[0]
+                        if isinstance(c, dict):
+                            cit_str = f"{c.get('volume', '')} {c.get('reporter', '')} {c.get('page', '')}".strip()
+                        elif isinstance(c, str):
+                            cit_str = c
+                    results.append({
+                        "citation": cit_str or cluster.get("case_name", ""),
+                        "normalized_citations": [cit_str] if cit_str else [],
+                        "status": 200,
+                        "error_message": "",
+                        "clusters": [cluster],
+                    })
+                    return results
+
+            # Not found
+            results.append({
+                "citation": text,
+                "normalized_citations": [],
+                "status": 404,
+                "error_message": "Citation not found in database.",
+                "clusters": [],
+            })
+
+        return results
+
+    # ==================================================================
+    # DOCKETS & FILINGS
+    # ==================================================================
+
+    def get_docket(self, docket_id: int) -> dict:
+        """Get docket by ID (mirrors GET /dockets/{id}/)."""
+        docket = self._dockets.get(docket_id)
+        if not docket:
+            return {"detail": "Not found."}
+        return dict(docket)
+
+    def get_docket_entries(self, docket: int = 0, page_size: int = 20) -> dict:
+        """Get docket entries (mirrors GET /docket-entries/)."""
+        results = []
+        for eid, entry in self._docket_entries.items():
+            if docket:
+                entry_docket_url = entry.get("docket", "")
+                if self._extract_id_from_url(entry_docket_url) != docket:
+                    continue
+            results.append(entry)
+        results.sort(key=lambda x: x.get("entry_number", 0))
+        return self._paginate(results, page_size)
+
+    def get_recap_document(self, rd_id: int) -> dict:
+        """Get RECAP document by ID (mirrors GET /recap-documents/{id}/)."""
+        doc = self._recap_documents.get(rd_id)
+        if not doc:
+            return {"detail": "Not found."}
+        return dict(doc)
+
+    def get_parties(self, docket: int = 0, page_size: int = 20) -> dict:
+        """Get parties (mirrors GET /parties/)."""
+        results = []
+        for pid, party in self._parties.items():
+            if docket:
+                party_docket_url = party.get("docket", "")
+                if self._extract_id_from_url(party_docket_url) != docket:
+                    continue
+            results.append(party)
+        return self._paginate(results, page_size)
+
+    def get_attorneys(self, docket: int = 0, page_size: int = 20) -> dict:
+        """Get attorneys (mirrors GET /attorneys/)."""
+        results = []
+        for aid, atty in self._attorneys.items():
+            if docket:
+                atty_docket_url = atty.get("docket", "")
+                if self._extract_id_from_url(atty_docket_url) != docket:
+                    continue
+            results.append(atty)
+        return self._paginate(results, page_size)
+
+    def get_bankruptcy_info(self, docket: int = 0) -> dict:
+        """Get bankruptcy information (mirrors GET /bankruptcy-information/)."""
+        results = []
+        for bid, info in self._bankruptcy_info.items():
+            if docket:
+                info_docket_url = info.get("docket", "")
+                if self._extract_id_from_url(info_docket_url) != docket:
+                    continue
+            results.append(info)
+        return self._paginate(results, 20)
+
+    def get_originating_court_info(self, docket: int = 0) -> dict:
+        """Get originating court information (mirrors GET /originating-court-information/)."""
+        results = []
+        for oid, info in self._originating_court_info.items():
+            if docket:
+                info_docket_url = info.get("docket", "")
+                if self._extract_id_from_url(info_docket_url) != docket:
+                    continue
+            results.append(info)
+        return self._paginate(results, 20)
+
+    def get_fjc_data(self, docket: int = 0, page_size: int = 20) -> dict:
+        """Get FJC integrated database records (mirrors GET /fjc-integrated-database/)."""
+        results = []
+        for fid, data in self._fjc_data.items():
+            if docket:
+                data_docket_url = data.get("docket", "")
+                if self._extract_id_from_url(data_docket_url) != docket:
+                    continue
+            results.append(data)
+        return self._paginate(results, page_size)
+
+    # ==================================================================
+    # COURTS
+    # ==================================================================
+
+    def get_court(self, court_id: str) -> dict:
+        """Get court by ID (mirrors GET /courts/{id}/)."""
+        court = self._courts.get(court_id)
+        if not court:
+            return {"detail": "Not found."}
+        return dict(court)
+
+    # ==================================================================
+    # ORAL ARGUMENTS
+    # ==================================================================
+
+    def get_audio(self, audio_id: int) -> dict:
+        """Get oral argument by ID (mirrors GET /audio/{id}/)."""
+        audio = self._audio.get(audio_id)
+        if not audio:
+            return {"detail": "Not found."}
+        return dict(audio)
+
+    # ==================================================================
+    # PEOPLE / JUDGES
+    # ==================================================================
+
+    def get_person(self, person_id: int) -> dict:
+        """Get person by ID (mirrors GET /people/{id}/)."""
+        person = self._people.get(person_id)
+        if not person:
+            return {"detail": "Not found."}
+        return dict(person)
+
+    def get_positions(self, person: int = 0, page_size: int = 20) -> dict:
+        """Get judicial positions (mirrors GET /positions/)."""
+        results = []
+        for pid, pos in self._positions.items():
+            if person:
+                pos_person_url = pos.get("person", "")
+                if self._extract_id_from_url(pos_person_url) != person:
+                    continue
+            results.append(pos)
+        return self._paginate(results, page_size)
+
+    def get_educations(self, person: int = 0, page_size: int = 20) -> dict:
+        """Get education records (mirrors GET /educations/)."""
+        results = []
+        for eid, edu in self._educations.items():
+            if person:
+                edu_person_url = edu.get("person", "")
+                if self._extract_id_from_url(edu_person_url) != person:
+                    continue
+            results.append(edu)
+        return self._paginate(results, page_size)
+
+    def get_political_affiliations(self, person: int = 0, page_size: int = 20) -> dict:
+        """Get political affiliations (mirrors GET /political-affiliations/)."""
+        results = []
+        for paid, pa in self._political_affiliations.items():
+            if person:
+                pa_person_url = pa.get("person", "")
+                if self._extract_id_from_url(pa_person_url) != person:
+                    continue
+            results.append(pa)
+        return self._paginate(results, page_size)
+
+    def get_aba_ratings(self, person: int = 0, page_size: int = 20) -> dict:
+        """Get ABA ratings (mirrors GET /aba-ratings/)."""
+        results = []
+        for rid, rating in self._aba_ratings.items():
+            if person:
+                rating_person_url = rating.get("person", "")
+                if self._extract_id_from_url(rating_person_url) != person:
+                    continue
+            results.append(rating)
+        return self._paginate(results, page_size)
+
+    # ==================================================================
+    # FINANCIAL DISCLOSURES
+    # ==================================================================
+
+    def get_financial_disclosures(self, person: int = 0, year: int = 0,
+                                   page_size: int = 20) -> dict:
+        """Get financial disclosures (mirrors GET /financial-disclosures/)."""
+        results = []
+        for fid, disc in self._financial_disclosures.items():
+            if person:
+                disc_person_url = disc.get("person", "")
+                if self._extract_id_from_url(disc_person_url) != person:
+                    continue
+            if year and disc.get("year") != year:
+                continue
+            results.append(disc)
+        return self._paginate(results, page_size)
+
+    def _filter_by_financial_disclosure(self, store: dict, financial_disclosure: int = 0,
+                                         page_size: int = 20) -> dict:
+        """Generic filter for financial disclosure sub-tables."""
+        results = []
+        for iid, item in store.items():
+            if financial_disclosure:
+                fd_url = item.get("financial_disclosure", "")
+                if self._extract_id_from_url(fd_url) != financial_disclosure:
+                    continue
+            results.append(item)
+        return self._paginate(results, page_size)
+
+    def get_investments(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._investments, financial_disclosure, page_size)
+
+    def get_gifts(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._gifts, financial_disclosure, page_size)
+
+    def get_debts(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._debts, financial_disclosure, page_size)
+
+    def get_agreements(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._agreements, financial_disclosure, page_size)
+
+    def get_non_investment_incomes(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._non_investment_incomes, financial_disclosure, page_size)
+
+    def get_disclosure_positions(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._disclosure_positions, financial_disclosure, page_size)
+
+    def get_reimbursements(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._reimbursements, financial_disclosure, page_size)
+
+    def get_spouse_incomes(self, financial_disclosure: int = 0, page_size: int = 20) -> dict:
+        return self._filter_by_financial_disclosure(self._spouse_incomes, financial_disclosure, page_size)