rdubwiley commited on
Commit
459bdc8
Β·
verified Β·
1 Parent(s): 84897ce

Deploy Agenda Parser

Browse files
cornell_lii/__init__.py ADDED
@@ -0,0 +1,16 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """cornell_lii β€” a Typer CLI for querying the Cornell Legal Information Institute.
2
+
3
+ Turns federal/state regulation (and federal statute) citations into links back to
4
+ the pages Cornell LII hosts at https://www.law.cornell.edu/ . Links are built
5
+ deterministically with no network by default; the eCFR API is used only to
6
+ optionally ``--verify`` a CFR citation and to power federal ``search``.
7
+
8
+ Run as::
9
+
10
+ uv run python -m cornell_lii --help
11
+ """
12
+ from __future__ import annotations
13
+
14
+ from .cli import app
15
+
16
+ __all__ = ["app"]
cornell_lii/__main__.py ADDED
@@ -0,0 +1,7 @@
 
 
 
 
 
 
 
 
1
+ """Entry point so ``python -m cornell_lii ...`` works."""
2
+ from __future__ import annotations
3
+
4
+ from .cli import app
5
+
6
+ if __name__ == "__main__":
7
+ app()
cornell_lii/citations.py ADDED
@@ -0,0 +1,67 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Parse and normalize US legal citations (CFR regulations, USC statutes).
2
+
3
+ Pure and network-free. Tolerant of the common written forms::
4
+
5
+ 29 CFR 1604.11 29 C.F.R. Β§ 1604.11 29/1604.11
6
+ 42 USC 1983 42 U.S.C. Β§ 1983 42/1983
7
+
8
+ A parsed citation carries the corpus ("cfr"/"usc"), the title number, and the
9
+ section as written (subsection parentheticals are preserved here and only dropped
10
+ when building the per-section page URL in ``urls``).
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from dataclasses import dataclass
16
+
17
+ __all__ = ["Citation", "CitationError", "parse_cfr", "parse_usc"]
18
+
19
+
20
+ class CitationError(ValueError):
21
+ """Raised when a citation string cannot be parsed."""
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Citation:
26
+ corpus: str # "cfr" | "usc"
27
+ title: str
28
+ section: str
29
+
30
+ @property
31
+ def label(self) -> str:
32
+ word = "CFR" if self.corpus == "cfr" else "USC"
33
+ return f"{self.title} {word} {self.section}"
34
+
35
+
36
+ # Match the corpus token in any common spelling (CFR / C.F.R. / USC / U.S.C.) and
37
+ # the section sign, so they can be stripped before pulling out the numbers.
38
+ _CORPUS_RE = re.compile(r"(?i)\b(?:c\.?\s*f\.?\s*r\.?|u\.?\s*s\.?\s*c\.?)\b|Β§")
39
+
40
+
41
+ def _split_title_section(text: str, *, corpus: str) -> tuple[str, str]:
42
+ cleaned = _CORPUS_RE.sub(" ", text)
43
+ cleaned = cleaned.replace("/", " ")
44
+ tokens = [t.strip(".,;") for t in cleaned.split() if t.strip(".,;")]
45
+ nums = [t for t in tokens if any(ch.isdigit() for ch in t)]
46
+ word = "CFR" if corpus == "cfr" else "USC"
47
+ if len(nums) < 2:
48
+ raise CitationError(
49
+ f"Could not read a {word} citation from {text!r}. "
50
+ f"Expected something like '29 {word} 1604.11'."
51
+ )
52
+ title, section = nums[0], nums[1]
53
+ if not title.isdigit():
54
+ raise CitationError(f"{title!r} is not a valid {word} title number (from {text!r}).")
55
+ return title, section
56
+
57
+
58
+ def parse_cfr(text: str) -> Citation:
59
+ """Parse a Code of Federal Regulations citation, e.g. ``29 CFR 1604.11``."""
60
+ title, section = _split_title_section(text, corpus="cfr")
61
+ return Citation("cfr", title, section)
62
+
63
+
64
+ def parse_usc(text: str) -> Citation:
65
+ """Parse a US Code citation, e.g. ``42 USC 1983``."""
66
+ title, section = _split_title_section(text, corpus="usc")
67
+ return Citation("usc", title, section)
cornell_lii/cli.py ADDED
@@ -0,0 +1,213 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Typer CLI: turn federal/state regulation & statute citations into Cornell LII links.
2
+
3
+ Links are built offline by default. ``--verify`` (CFR) and ``search`` (federal)
4
+ are the only paths that reach the network, via the public eCFR API.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import typer
9
+
10
+ from . import citations, ecfr, output, states, urls
11
+ from .citations import Citation, CitationError
12
+ from .client import HttpError, url_exists
13
+
14
+ app = typer.Typer(
15
+ add_completion=False,
16
+ no_args_is_help=True,
17
+ help="Query Cornell LII (law.cornell.edu) for federal & state regulation links.",
18
+ )
19
+
20
+ # Reusable --json flag, shared across commands.
21
+ JSON = typer.Option(False, "--json", "-j", help="Emit JSON instead of human-readable text.")
22
+
23
+
24
+ def _fail(message: str) -> "typer.NoReturn":
25
+ typer.secho(f"error: {message}", fg=typer.colors.RED, err=True)
26
+ raise typer.Exit(1)
27
+
28
+
29
+ def _parse(text: str | None, title: str | None, section: str | None, corpus: str) -> Citation:
30
+ """Build a Citation from a free-form string or explicit --title/--section."""
31
+ if text:
32
+ try:
33
+ return citations.parse_cfr(text) if corpus == "cfr" else citations.parse_usc(text)
34
+ except CitationError as e:
35
+ _fail(str(e))
36
+ if title and section:
37
+ return Citation(corpus, str(title), str(section))
38
+ word = "CFR" if corpus == "cfr" else "USC"
39
+ _fail(f"Provide a citation (e.g. '29 {word} 1604.11') or both --title and --section.")
40
+
41
+
42
+ # --- Federal CFR (regulations) ------------------------------------------------
43
+
44
+ @app.command()
45
+ def cfr(
46
+ citation: str = typer.Argument(None, help="e.g. '29 CFR 1604.11' or '29/1604.11'"),
47
+ title: str = typer.Option(None, "--title", "-t", help="CFR title number."),
48
+ section: str = typer.Option(None, "--section", "-s", help="Section number, e.g. 1604.11."),
49
+ verify: bool = typer.Option(False, "--verify", help="Confirm the citation exists via the eCFR API."),
50
+ json_out: bool = JSON,
51
+ ) -> None:
52
+ """Resolve a Code of Federal Regulations citation to its LII page."""
53
+ cit = _parse(citation, title, section, "cfr")
54
+ result = {
55
+ "corpus": "cfr",
56
+ "citation": cit.label,
57
+ "title": cit.title,
58
+ "section": cit.section,
59
+ "url": urls.cfr_section_url(cit.title, cit.section),
60
+ }
61
+ if verify:
62
+ try:
63
+ v = ecfr.verify_cfr(cit.title, cit.section)
64
+ except HttpError as e:
65
+ _fail(f"eCFR verification failed: {e}")
66
+ result["verified"] = v["valid"]
67
+ result["date"] = v["date"]
68
+ if v.get("heading"):
69
+ result["label"] = v["heading"]
70
+ if v.get("detail"):
71
+ result["detail"] = v["detail"]
72
+ output.show(result, json_out)
73
+
74
+
75
+ @app.command("cfr-part")
76
+ def cfr_part(
77
+ title: str = typer.Argument(..., help="CFR title number, e.g. 29."),
78
+ part: str = typer.Argument(..., help="Part number, e.g. 1604."),
79
+ json_out: bool = JSON,
80
+ ) -> None:
81
+ """Link to a CFR part's browse page (lists its sections)."""
82
+ result = {
83
+ "corpus": "cfr",
84
+ "citation": f"{title} CFR Part {part}",
85
+ "url": urls.cfr_part_url(title, part),
86
+ }
87
+ output.show(result, json_out)
88
+
89
+
90
+ @app.command("cfr-title")
91
+ def cfr_title(
92
+ title: str = typer.Argument(..., help="CFR title number, e.g. 29."),
93
+ json_out: bool = JSON,
94
+ ) -> None:
95
+ """Link to a CFR title's index page."""
96
+ result = {"corpus": "cfr", "citation": f"{title} CFR", "url": urls.cfr_title_url(title)}
97
+ output.show(result, json_out)
98
+
99
+
100
+ # --- Federal USC (statutes) ---------------------------------------------------
101
+
102
+ @app.command()
103
+ def usc(
104
+ citation: str = typer.Argument(None, help="e.g. '42 USC 1983' or '42/1983'"),
105
+ title: str = typer.Option(None, "--title", "-t", help="USC title number."),
106
+ section: str = typer.Option(None, "--section", "-s", help="Section number, e.g. 1983."),
107
+ verify: bool = typer.Option(False, "--verify", help="Confirm the LII page resolves (HTTP check)."),
108
+ json_out: bool = JSON,
109
+ ) -> None:
110
+ """Resolve a US Code citation to its LII page."""
111
+ cit = _parse(citation, title, section, "usc")
112
+ url = urls.usc_section_url(cit.title, cit.section)
113
+ result = {
114
+ "corpus": "usc",
115
+ "citation": cit.label,
116
+ "title": cit.title,
117
+ "section": cit.section,
118
+ "url": url,
119
+ }
120
+ if verify:
121
+ ok = url_exists(url)
122
+ result["verified"] = ok
123
+ if not ok:
124
+ result["detail"] = "LII page did not return HTTP 200."
125
+ output.show(result, json_out)
126
+
127
+
128
+ # --- State materials ----------------------------------------------------------
129
+
130
+ @app.command("state-regs")
131
+ def state_regs(
132
+ state: str = typer.Argument(..., help="State name or USPS abbreviation, e.g. 'maine' or 'ME'."),
133
+ json_out: bool = JSON,
134
+ ) -> None:
135
+ """Link to a state's LII-hosted administrative code (regulations)."""
136
+ try:
137
+ slug = states.resolve_state(state)
138
+ except ValueError as e:
139
+ _fail(str(e))
140
+ result = {
141
+ "corpus": "state-regs",
142
+ "citation": f"{slug.replace('_', ' ').title()} regulations",
143
+ "url": urls.state_regs_url(slug),
144
+ }
145
+ output.show(result, json_out)
146
+
147
+
148
+ @app.command()
149
+ def state(
150
+ state: str = typer.Argument(..., help="State name or USPS abbreviation, e.g. 'new york' or 'NY'."),
151
+ json_out: bool = JSON,
152
+ ) -> None:
153
+ """Link to a state's LII portal page (statutes link out to official sources)."""
154
+ try:
155
+ slug = states.resolve_state(state)
156
+ except ValueError as e:
157
+ _fail(str(e))
158
+ result = {
159
+ "corpus": "state",
160
+ "citation": f"{slug.replace('_', ' ').title()} legal materials",
161
+ "url": urls.state_portal_url(slug),
162
+ }
163
+ output.show(result, json_out)
164
+
165
+
166
+ @app.command("states")
167
+ def states_cmd(json_out: bool = JSON) -> None:
168
+ """Link to the LII states & regulations directories."""
169
+ result = {
170
+ "links": [
171
+ {"citation": "All states", "url": urls.states_directory_url()},
172
+ {"citation": "All state regulations", "url": urls.regulations_directory_url()},
173
+ ]
174
+ }
175
+ output.show(result, json_out)
176
+
177
+
178
+ # --- Search -------------------------------------------------------------------
179
+
180
+ @app.command()
181
+ def search(
182
+ query: str = typer.Argument(..., help="Search terms."),
183
+ corpus: str = typer.Option("cfr", "--corpus", "-c", help="'cfr' = eCFR API deep links; 'lii' = LII site-search URL."),
184
+ limit: int = typer.Option(10, "--limit", "-n", help="Max results (cfr corpus)."),
185
+ json_out: bool = JSON,
186
+ ) -> None:
187
+ """Search federal regulations (eCFR -> LII links), or get the LII site-search URL."""
188
+ corpus = corpus.lower()
189
+ if corpus == "cfr":
190
+ try:
191
+ hits = ecfr.search_federal(query, limit)
192
+ except HttpError as e:
193
+ _fail(f"eCFR search failed: {e}")
194
+ output.show({"query": query, "corpus": "cfr", "links": hits}, json_out, attribution=True)
195
+ elif corpus == "lii":
196
+ result = {
197
+ "query": query,
198
+ "corpus": "lii",
199
+ "links": [
200
+ {
201
+ "citation": f"LII site search: {query}",
202
+ "url": urls.lii_search_url(query),
203
+ "note": "Open in a browser β€” LII search is not crawlable (robots.txt) and renders client-side.",
204
+ }
205
+ ],
206
+ }
207
+ output.show(result, json_out, attribution=True)
208
+ else:
209
+ _fail("--corpus must be 'cfr' or 'lii'.")
210
+
211
+
212
+ if __name__ == "__main__":
213
+ app()
cornell_lii/client.py ADDED
@@ -0,0 +1,50 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Shared HTTP helpers (httpx) for the cornell_lii CLI.
2
+
3
+ Only ``--verify`` and federal ``search`` touch the network; everything else is
4
+ pure URL construction. A descriptive User-Agent is sent on every request.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ from typing import Any
9
+
10
+ import httpx
11
+
12
+ __all__ = ["USER_AGENT", "HttpError", "get_json", "url_exists"]
13
+
14
+ USER_AGENT = "cornell-lii-cli/0.1 (legal research; +https://www.law.cornell.edu)"
15
+ _TIMEOUT = 30.0
16
+
17
+
18
+ class HttpError(RuntimeError):
19
+ """Any network/HTTP failure, normalized for the CLI to report."""
20
+
21
+
22
+ def _client(accept: str = "application/json") -> httpx.Client:
23
+ return httpx.Client(
24
+ timeout=_TIMEOUT,
25
+ follow_redirects=True,
26
+ headers={"User-Agent": USER_AGENT, "Accept": accept},
27
+ )
28
+
29
+
30
+ def get_json(url: str, params: dict[str, Any] | None = None) -> Any:
31
+ """GET ``url`` and return parsed JSON, raising ``HttpError`` on any failure."""
32
+ try:
33
+ with _client() as c:
34
+ r = c.get(url, params=params)
35
+ r.raise_for_status()
36
+ return r.json()
37
+ except httpx.HTTPError as e:
38
+ raise HttpError(str(e)) from e
39
+
40
+
41
+ def url_exists(url: str) -> bool:
42
+ """True if ``url`` resolves to HTTP 200 (HEAD, falling back to GET)."""
43
+ try:
44
+ with _client(accept="text/html") as c:
45
+ r = c.head(url)
46
+ if r.status_code in (403, 405): # some servers reject HEAD
47
+ r = c.get(url)
48
+ return r.status_code == 200
49
+ except httpx.HTTPError:
50
+ return False
cornell_lii/ecfr.py ADDED
@@ -0,0 +1,96 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """eCFR API client (https://www.ecfr.gov) β€” validate CFR citations and search.
2
+
3
+ Federal CFR only. eCFR content is public domain and the API needs no key. Hits
4
+ are mapped back to Cornell LII page URLs via ``urls`` so the CLI's links always
5
+ point at LII even though the data comes from eCFR.
6
+
7
+ Endpoints used (verified against the live API):
8
+ - GET /api/versioner/v1/titles.json -> available titles + current date
9
+ - GET /api/versioner/v1/ancestry/{date}/title-{title}.json -> validate a section (404 if absent)
10
+ - GET /api/search/v1/results?query=... -> full-text search hits
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from typing import Any
16
+
17
+ from . import urls
18
+ from .client import HttpError, get_json
19
+
20
+ __all__ = ["ECFR_BASE", "verify_cfr", "search_federal"]
21
+
22
+ ECFR_BASE = "https://www.ecfr.gov"
23
+ _TAG_RE = re.compile(r"<[^>]+>")
24
+ _WS_RE = re.compile(r"\s+")
25
+
26
+
27
+ def _clean(text: str | None) -> str | None:
28
+ """eCFR wraps matched terms and ellipses in HTML; strip tags and tidy whitespace."""
29
+ if not text:
30
+ return text
31
+ return _WS_RE.sub(" ", _TAG_RE.sub("", text)).strip()
32
+
33
+
34
+ def _latest_date(title: str) -> str | None:
35
+ data = get_json(f"{ECFR_BASE}/api/versioner/v1/titles.json")
36
+ for t in data.get("titles", []):
37
+ if str(t.get("number")) == str(title):
38
+ return t.get("up_to_date_as_of") or t.get("latest_issue_date")
39
+ return None
40
+
41
+
42
+ def verify_cfr(title: str, section: str) -> dict[str, Any]:
43
+ """Confirm ``{title} CFR {section}`` exists via the eCFR ancestry endpoint.
44
+
45
+ Returns ``{"valid": bool, "date": str|None, "heading": str|None, "detail": str|None}``.
46
+ """
47
+ section = re.split(r"[(\s]", section.strip(), maxsplit=1)[0]
48
+ date = _latest_date(title)
49
+ if not date:
50
+ return {"valid": False, "date": None, "heading": None, "detail": f"No CFR Title {title}."}
51
+
52
+ url = f"{ECFR_BASE}/api/versioner/v1/ancestry/{date}/title-{title}.json"
53
+ try:
54
+ data = get_json(url, params={"section": section})
55
+ except HttpError:
56
+ return {
57
+ "valid": False,
58
+ "date": date,
59
+ "heading": None,
60
+ "detail": f"Β§ {section} not found in Title {title} (as of {date}).",
61
+ }
62
+
63
+ heading = None
64
+ for anc in data.get("ancestors", []):
65
+ if anc.get("type") == "section":
66
+ heading = _clean(anc.get("label"))
67
+ return {"valid": True, "date": date, "heading": heading, "detail": None}
68
+
69
+
70
+ def search_federal(query: str, limit: int = 10) -> list[dict[str, Any]]:
71
+ """Full-text search the eCFR; return hits as LII links (most specific level)."""
72
+ data = get_json(
73
+ f"{ECFR_BASE}/api/search/v1/results",
74
+ params={"query": query, "per_page": min(max(limit, 1), 20)},
75
+ )
76
+ hits: list[dict[str, Any]] = []
77
+ for item in data.get("results", [])[:limit]:
78
+ h = item.get("hierarchy", {})
79
+ hd = item.get("headings", {})
80
+ title, section, part = h.get("title"), h.get("section"), h.get("part")
81
+ if section:
82
+ url, cite = urls.cfr_section_url(title, section), f"{title} CFR {section}"
83
+ elif part:
84
+ url, cite = urls.cfr_part_url(title, part), f"{title} CFR Part {part}"
85
+ else:
86
+ url, cite = urls.cfr_title_url(title), f"{title} CFR"
87
+ label = _clean(hd.get("section") or hd.get("part") or hd.get("title")) or cite
88
+ hits.append(
89
+ {
90
+ "citation": cite,
91
+ "label": label,
92
+ "url": url,
93
+ "excerpt": _clean(item.get("full_text_excerpt")),
94
+ }
95
+ )
96
+ return hits
cornell_lii/output.py ADDED
@@ -0,0 +1,87 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Render command results: human-readable (Rich if available) or JSON.
2
+
3
+ Every command produces a plain dict. ``show`` either dumps it as JSON (``--json``)
4
+ or prints a readable block. A result is either a single link dict or a dict with a
5
+ ``"links"`` list; recognized per-link keys: ``citation``/``label``/``title``
6
+ (heading text), ``url``, ``verified``/``date`` (verification), ``excerpt``, ``note``.
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import json as _json
11
+ import sys
12
+ from typing import Any
13
+
14
+ __all__ = ["show", "ATTRIBUTION"]
15
+
16
+ ATTRIBUTION = "Source: Cornell LII (CC BY-NC-SA 2.5) β€” https://www.law.cornell.edu"
17
+
18
+ try: # rich ships with typer; degrade gracefully if absent
19
+ from rich.console import Console
20
+
21
+ _out: Console | None = Console()
22
+ _err: Console | None = Console(stderr=True)
23
+ except Exception: # pragma: no cover - fallback path
24
+ _out = _err = None
25
+
26
+
27
+ def _esc(text: str) -> str:
28
+ return text.replace("[", r"\[")
29
+
30
+
31
+ def _render_link(link: dict[str, Any]) -> None:
32
+ cite = link.get("citation") or link.get("title") or ""
33
+ heading = link.get("label") or link.get("heading")
34
+ head = cite
35
+ if heading and heading != cite:
36
+ head = f"{cite} β€” {heading}" if cite else heading
37
+ url = link.get("url", "")
38
+
39
+ if _out is not None:
40
+ _out.print(f"[bold]{_esc(head)}[/bold]" if head else "")
41
+ if url:
42
+ _out.print(f" [link={url}]{url}[/link]", style="cyan")
43
+ else:
44
+ if head:
45
+ print(head)
46
+ if url:
47
+ print(f" {url}")
48
+
49
+ if "verified" in link:
50
+ if link["verified"]:
51
+ asof = f" (as of {link['date']})" if link.get("date") else ""
52
+ _line(f" verified βœ“{asof}", style="green")
53
+ else:
54
+ _line(f" not found βœ— β€” {link.get('detail') or 'citation does not resolve'}", style="yellow")
55
+ if link.get("excerpt"):
56
+ _line(f" …{link['excerpt']}…", style="dim")
57
+ if link.get("note"):
58
+ _line(f" {link['note']}", style="dim")
59
+
60
+
61
+ def _line(text: str, *, style: str = "") -> None:
62
+ if _out is not None:
63
+ _out.print(_esc(text), style=style or None)
64
+ else:
65
+ print(text)
66
+
67
+
68
+ def show(result: dict[str, Any], as_json: bool, *, attribution: bool = False) -> None:
69
+ if as_json:
70
+ print(_json.dumps(result, indent=2))
71
+ return
72
+
73
+ links = result.get("links")
74
+ if links is None:
75
+ links = [result]
76
+ if not links:
77
+ _line("No results.", style="yellow")
78
+ for i, link in enumerate(links):
79
+ _render_link(link)
80
+ if i < len(links) - 1:
81
+ _line("")
82
+
83
+ if attribution:
84
+ if _err is not None:
85
+ _err.print(f"[dim]{ATTRIBUTION}[/dim]")
86
+ else:
87
+ print(ATTRIBUTION, file=sys.stderr)
cornell_lii/states.py ADDED
@@ -0,0 +1,43 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Map a US state name or 2-letter abbreviation to its Cornell LII slug.
2
+
3
+ LII slugs are the lowercase state name with spaces as underscores
4
+ (e.g. ``new_york``, ``district_of_columbia``).
5
+ """
6
+ from __future__ import annotations
7
+
8
+ __all__ = ["resolve_state", "STATE_SLUGS"]
9
+
10
+ # (slug, USPS abbreviation). The display name is the slug with underscores -> spaces.
11
+ _STATES: list[tuple[str, str]] = [
12
+ ("alabama", "AL"), ("alaska", "AK"), ("arizona", "AZ"), ("arkansas", "AR"),
13
+ ("california", "CA"), ("colorado", "CO"), ("connecticut", "CT"), ("delaware", "DE"),
14
+ ("district_of_columbia", "DC"), ("florida", "FL"), ("georgia", "GA"), ("hawaii", "HI"),
15
+ ("idaho", "ID"), ("illinois", "IL"), ("indiana", "IN"), ("iowa", "IA"),
16
+ ("kansas", "KS"), ("kentucky", "KY"), ("louisiana", "LA"), ("maine", "ME"),
17
+ ("maryland", "MD"), ("massachusetts", "MA"), ("michigan", "MI"), ("minnesota", "MN"),
18
+ ("mississippi", "MS"), ("missouri", "MO"), ("montana", "MT"), ("nebraska", "NE"),
19
+ ("nevada", "NV"), ("new_hampshire", "NH"), ("new_jersey", "NJ"), ("new_mexico", "NM"),
20
+ ("new_york", "NY"), ("north_carolina", "NC"), ("north_dakota", "ND"), ("ohio", "OH"),
21
+ ("oklahoma", "OK"), ("oregon", "OR"), ("pennsylvania", "PA"), ("rhode_island", "RI"),
22
+ ("south_carolina", "SC"), ("south_dakota", "SD"), ("tennessee", "TN"), ("texas", "TX"),
23
+ ("utah", "UT"), ("vermont", "VT"), ("virginia", "VA"), ("washington", "WA"),
24
+ ("west_virginia", "WV"), ("wisconsin", "WI"), ("wyoming", "WY"),
25
+ ]
26
+
27
+ STATE_SLUGS: tuple[str, ...] = tuple(slug for slug, _ in _STATES)
28
+ _BY_ABBR: dict[str, str] = {abbr.lower(): slug for slug, abbr in _STATES}
29
+ _SLUG_SET = set(STATE_SLUGS)
30
+
31
+
32
+ def resolve_state(text: str) -> str:
33
+ """Return the LII slug for ``text`` (a state name or USPS abbreviation).
34
+
35
+ Raises ``ValueError`` for an unrecognized state.
36
+ """
37
+ key = text.strip().lower()
38
+ if len(key) == 2 and key in _BY_ABBR:
39
+ return _BY_ABBR[key]
40
+ slug = key.replace("-", "_").replace(" ", "_").replace(".", "")
41
+ if slug in _SLUG_SET:
42
+ return slug
43
+ raise ValueError(f"Unrecognized state {text!r}. Use a full name or USPS abbreviation (e.g. 'NY').")
cornell_lii/urls.py ADDED
@@ -0,0 +1,99 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Build Cornell LII page URLs from normalized citation parts. Pure, no network.
2
+
3
+ These are the verified deterministic templates LII uses; see the project plan for
4
+ the example URLs each was confirmed against.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import re
9
+ import urllib.parse
10
+
11
+ __all__ = [
12
+ "LII_BASE",
13
+ "cfr_section_url",
14
+ "cfr_part_url",
15
+ "cfr_title_url",
16
+ "cfr_index_url",
17
+ "usc_section_url",
18
+ "usc_title_url",
19
+ "usc_index_url",
20
+ "state_regs_url",
21
+ "state_portal_url",
22
+ "states_directory_url",
23
+ "regulations_directory_url",
24
+ "lii_search_url",
25
+ ]
26
+
27
+ LII_BASE = "https://www.law.cornell.edu"
28
+
29
+
30
+ def _section_path(section: str) -> str:
31
+ """The per-section page is keyed by the bare section number.
32
+
33
+ LII serves one page per section, so any ``(a)``-style subsection suffix is
34
+ dropped for the URL (``1604.11(a)`` -> ``1604.11``).
35
+ """
36
+ return re.split(r"[(\s]", section.strip(), maxsplit=1)[0]
37
+
38
+
39
+ # --- Federal CFR (regulations) ------------------------------------------------
40
+
41
+ def cfr_section_url(title: str, section: str) -> str:
42
+ return f"{LII_BASE}/cfr/text/{title}/{_section_path(section)}"
43
+
44
+
45
+ def cfr_part_url(title: str, part: str) -> str:
46
+ return f"{LII_BASE}/cfr/text/{title}/part-{part}"
47
+
48
+
49
+ def cfr_title_url(title: str) -> str:
50
+ return f"{LII_BASE}/cfr/text/{title}"
51
+
52
+
53
+ def cfr_index_url() -> str:
54
+ return f"{LII_BASE}/cfr/text"
55
+
56
+
57
+ # --- Federal USC (statutes) ---------------------------------------------------
58
+
59
+ def usc_section_url(title: str, section: str) -> str:
60
+ return f"{LII_BASE}/uscode/text/{title}/{_section_path(section)}"
61
+
62
+
63
+ def usc_title_url(title: str) -> str:
64
+ return f"{LII_BASE}/uscode/text/{title}"
65
+
66
+
67
+ def usc_index_url() -> str:
68
+ return f"{LII_BASE}/uscode/text"
69
+
70
+
71
+ # --- State materials ----------------------------------------------------------
72
+
73
+ def state_regs_url(slug: str) -> str:
74
+ """LII-hosted state administrative code, e.g. ``/regulations/maine``."""
75
+ return f"{LII_BASE}/regulations/{slug}"
76
+
77
+
78
+ def state_portal_url(slug: str) -> str:
79
+ """State portal page (links out to official statute sources), ``/states/{slug}``."""
80
+ return f"{LII_BASE}/states/{slug}"
81
+
82
+
83
+ def states_directory_url() -> str:
84
+ return f"{LII_BASE}/states"
85
+
86
+
87
+ def regulations_directory_url() -> str:
88
+ return f"{LII_BASE}/regulations"
89
+
90
+
91
+ # --- Site search --------------------------------------------------------------
92
+
93
+ def lii_search_url(query: str) -> str:
94
+ """LII's own site-search results URL (to open in a browser).
95
+
96
+ Not scraped: ``robots.txt`` disallows ``/search/`` and the results are
97
+ rendered client-side, so we hand the user the link rather than crawl it.
98
+ """
99
+ return f"{LII_BASE}/search/site?search_api_fulltext=" + urllib.parse.quote_plus(query)
webapp/agent_loop.py CHANGED
@@ -19,6 +19,7 @@ tool results, and final answer to the React UI live.
19
  from __future__ import annotations
20
 
21
  import json
 
22
  from typing import Callable, Iterator
23
 
24
  from webapp.agent_tools import (
@@ -140,27 +141,66 @@ def _result_summary(tool: str, result: dict) -> str:
140
  return ""
141
 
142
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
143
  def agent_turn(
144
  messages: list[dict],
145
- ctx: ToolContext,
146
  complete: Callable[..., str],
147
  *,
148
  max_steps: int = DEFAULT_MAX_STEPS,
 
149
  ) -> Iterator[dict]:
150
  """Run one user turn of the ReAct loop, yielding progress/result frames.
151
 
152
  Args:
153
  messages: the full chat so far (list of ``{"role", "content"}``), ending with
154
  the user's current message.
155
- ctx: the pinned jurisdiction/meeting context + LLM completer for tools.
 
 
156
  complete: ``complete(prompt, system=...) -> str`` the agent reasons with.
157
  max_steps: maximum tool calls before the loop force-stops.
 
 
158
 
159
  Frames (``{"stage", ...}``):
160
  ``thinking`` (text, step) Β· ``tool_call`` (tool, args, step) Β·
161
  ``tool_result`` (tool, result, step) Β· ``answer`` (text) Β· ``error`` (text).
162
  """
163
- system = _system_prompt(ctx)
 
164
  history = _render_history(messages)
165
  scratchpad: list[str] = []
166
  parse_fails = 0
@@ -204,17 +244,17 @@ def agent_turn(
204
  if thought:
205
  yield {"stage": "thinking", "text": thought, "step": step}
206
 
207
- if tool == FINAL_ANSWER:
208
  answer = str(targs.get("answer") or action.get("answer") or "").strip()
209
  yield {"stage": "answer", "text": answer or "(no answer)"}
210
  return
211
 
212
  yield {"stage": "tool_call", "tool": tool, "args": targs, "step": step}
213
- result = run_tool(tool, targs, ctx)
214
- obs = observation_text(result)
215
  yield {
216
  "stage": "tool_result", "tool": tool, "result": obs,
217
- "summary": _result_summary(tool, result), "step": step,
218
  }
219
  scratchpad.append(
220
  f'ACTION: {json.dumps({"tool": tool, "args": targs}, ensure_ascii=False)}\n'
 
19
  from __future__ import annotations
20
 
21
  import json
22
+ from dataclasses import dataclass
23
  from typing import Callable, Iterator
24
 
25
  from webapp.agent_tools import (
 
141
  return ""
142
 
143
 
144
+ @dataclass(frozen=True)
145
+ class Toolkit:
146
+ """The agenda-specific pieces the otherwise-generic loop plugs in.
147
+
148
+ Bundling these lets a second agent (e.g. the Cornell LII legal-research agent) reuse
149
+ the whole ReAct loop with a different toolset by passing its own ``Toolkit`` β€” only the
150
+ system prompt, tool dispatch, and result-summary differ; the protocol, JSON parsing,
151
+ scratchpad, retries, and budget logic are shared.
152
+
153
+ - ``system_prompt(ctx) -> str``: the agent's role + tool catalog + PROTOCOL.
154
+ - ``run_tool(name, args, ctx) -> dict``: dispatch one tool call (errors as ``{"error"}``).
155
+ - ``observation_text(result) -> str``: compact JSON of a result for the scratchpad.
156
+ - ``result_summary(tool, result) -> str``: one-line human gist for the live UI.
157
+ - ``final_answer``: the terminal pseudo-tool name that ends the turn.
158
+ """
159
+
160
+ system_prompt: Callable[..., str]
161
+ run_tool: Callable[..., dict]
162
+ observation_text: Callable[..., str]
163
+ result_summary: Callable[..., str]
164
+ final_answer: str
165
+
166
+
167
+ # The default toolkit β€” the uploaded-packet research agent (unchanged behavior).
168
+ AGENDA_TOOLKIT = Toolkit(
169
+ system_prompt=_system_prompt,
170
+ run_tool=run_tool,
171
+ observation_text=observation_text,
172
+ result_summary=_result_summary,
173
+ final_answer=FINAL_ANSWER,
174
+ )
175
+
176
+
177
  def agent_turn(
178
  messages: list[dict],
179
+ ctx: object,
180
  complete: Callable[..., str],
181
  *,
182
  max_steps: int = DEFAULT_MAX_STEPS,
183
+ toolkit: Toolkit | None = None,
184
  ) -> Iterator[dict]:
185
  """Run one user turn of the ReAct loop, yielding progress/result frames.
186
 
187
  Args:
188
  messages: the full chat so far (list of ``{"role", "content"}``), ending with
189
  the user's current message.
190
+ ctx: the tool context the toolkit's tools operate on (packet ``ToolContext`` for
191
+ the agenda agent, ``LiiContext`` for the LII agent) β€” passed straight through
192
+ to ``toolkit.run_tool``.
193
  complete: ``complete(prompt, system=...) -> str`` the agent reasons with.
194
  max_steps: maximum tool calls before the loop force-stops.
195
+ toolkit: which toolset/system-prompt to drive the loop with; defaults to the
196
+ agenda packet agent (:data:`AGENDA_TOOLKIT`).
197
 
198
  Frames (``{"stage", ...}``):
199
  ``thinking`` (text, step) Β· ``tool_call`` (tool, args, step) Β·
200
  ``tool_result`` (tool, result, step) Β· ``answer`` (text) Β· ``error`` (text).
201
  """
202
+ tk = toolkit or AGENDA_TOOLKIT
203
+ system = tk.system_prompt(ctx)
204
  history = _render_history(messages)
205
  scratchpad: list[str] = []
206
  parse_fails = 0
 
244
  if thought:
245
  yield {"stage": "thinking", "text": thought, "step": step}
246
 
247
+ if tool == tk.final_answer:
248
  answer = str(targs.get("answer") or action.get("answer") or "").strip()
249
  yield {"stage": "answer", "text": answer or "(no answer)"}
250
  return
251
 
252
  yield {"stage": "tool_call", "tool": tool, "args": targs, "step": step}
253
+ result = tk.run_tool(tool, targs, ctx)
254
+ obs = tk.observation_text(result)
255
  yield {
256
  "stage": "tool_result", "tool": tool, "result": obs,
257
+ "summary": tk.result_summary(tool, result), "step": step,
258
  }
259
  scratchpad.append(
260
  f'ACTION: {json.dumps({"tool": tool, "args": targs}, ensure_ascii=False)}\n'
webapp/backend.py CHANGED
@@ -1831,3 +1831,53 @@ def agent_chat(
1831
  {"stage": "error", "text": f"Agent failed: {type(e).__name__}: {e}"},
1832
  model=model_lbl,
1833
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1831
  {"stage": "error", "text": f"Agent failed: {type(e).__name__}: {e}"},
1832
  model=model_lbl,
1833
  )
1834
+
1835
+
1836
+ def lii_agent_chat(
1837
+ messages: list[AgentMessage],
1838
+ model: str = "",
1839
+ ) -> Iterator[AgentFrame]:
1840
+ """Stream one turn of the Cornell LII legal-research agent.
1841
+
1842
+ A ReAct loop over the legal tools (:mod:`webapp.lii_tools`) β€” searching the federal
1843
+ eCFR, resolving and verifying CFR/USC citations, and linking state materials on
1844
+ Cornell LII β€” then answering the user's latest message. Unlike :func:`agent_chat`
1845
+ this is **packet-independent** (no ``upload_id``); it researches public US law and
1846
+ its tools make live calls to the eCFR API / ``law.cornell.edu``.
1847
+
1848
+ On the ZeroGPU Space (``LLM_BACKEND=local``) the whole turn runs in one
1849
+ ``@spaces.GPU`` window; otherwise it runs against the remote vLLM endpoint.
1850
+
1851
+ Args:
1852
+ messages: the conversation so far, each ``{"role", "content"}``, ending with the
1853
+ user's current message.
1854
+ model: which in-process GGUF to use on the local backend; ignored remotely.
1855
+
1856
+ Yields :class:`AgentFrame` steps: ``thinking`` β†’ ``tool_call`` β†’ ``tool_result``
1857
+ (repeated) β†’ ``answer``, or ``error``.
1858
+ """
1859
+ if not messages or not (messages[-1].get("content") or "").strip():
1860
+ yield _agent_frame({"stage": "error", "text": "Ask a question to begin."})
1861
+ return
1862
+
1863
+ model_lbl = _model_label(model)
1864
+
1865
+ try:
1866
+ if LLM_BACKEND == "local":
1867
+ from webapp import local_llm
1868
+
1869
+ frames = local_llm.gpu_lii_agent_turn(list(messages), model)
1870
+ else:
1871
+ from webapp.agent_loop import agent_turn
1872
+ from webapp.lii_tools import TOOLKIT, LiiContext
1873
+
1874
+ ctx = LiiContext()
1875
+ frames = agent_turn(list(messages), ctx, _complete, toolkit=TOOLKIT)
1876
+
1877
+ for fr in frames:
1878
+ yield _agent_frame(fr, model=model_lbl)
1879
+ except Exception as e: # noqa: BLE001
1880
+ yield _agent_frame(
1881
+ {"stage": "error", "text": f"Agent failed: {type(e).__name__}: {e}"},
1882
+ model=model_lbl,
1883
+ )
webapp/frontend/dist/assets/{index-ihZX68Cf.js β†’ index-y7Mf8pNK.js} RENAMED
The diff for this file is too large to render. See raw diff
 
webapp/frontend/dist/index.html CHANGED
@@ -28,7 +28,7 @@
28
  href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%2314213a'/%3E%3Cpath d='M16 5 L26 11 H6 Z M8 13 v9 M13 13 v9 M19 13 v9 M24 13 v9 M5 24 h22 v2 H5 Z' stroke='%23c8a44d' stroke-width='1.6' fill='none' stroke-linejoin='round'/%3E%3C/svg%3E"
29
  />
30
  <title>Agenda Parser</title>
31
- <script type="module" crossorigin src="/assets/index-ihZX68Cf.js"></script>
32
  <link rel="stylesheet" crossorigin href="/assets/index-C8C9mTsY.css">
33
  </head>
34
  <body>
 
28
  href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%2314213a'/%3E%3Cpath d='M16 5 L26 11 H6 Z M8 13 v9 M13 13 v9 M19 13 v9 M24 13 v9 M5 24 h22 v2 H5 Z' stroke='%23c8a44d' stroke-width='1.6' fill='none' stroke-linejoin='round'/%3E%3C/svg%3E"
29
  />
30
  <title>Agenda Parser</title>
31
+ <script type="module" crossorigin src="/assets/index-y7Mf8pNK.js"></script>
32
  <link rel="stylesheet" crossorigin href="/assets/index-C8C9mTsY.css">
33
  </head>
34
  <body>
webapp/lii_tools.py ADDED
@@ -0,0 +1,378 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Tool registry for the Cornell LII legal-research agent.
2
+
3
+ A second Agent Mode toolset (see :mod:`webapp.agent_loop`), parallel to
4
+ :mod:`webapp.agent_tools` but pointed at **US federal/state law** instead of the uploaded
5
+ packet. Each tool is a thin wrapper over the :mod:`cornell_lii` library β€” resolving and
6
+ linking CFR/USC citations to the pages Cornell Legal Information Institute hosts, verifying
7
+ them and full-text-searching the public **eCFR API**.
8
+
9
+ Design notes:
10
+
11
+ * **Packet-independent.** These tools don't touch the uploaded PDF; the loop passes a
12
+ light :class:`LiiContext` (carrying only a per-turn network cache) straight through.
13
+ * **Links + excerpts, not full text.** LII content isn't scraped (its ``robots.txt``
14
+ disallows it). The agent returns citations, official LII links, and short eCFR search
15
+ excerpts β€” it must not invent statutory text. The system prompt enforces this.
16
+ * **Live external calls.** ``search_regulations`` and citation verification hit the eCFR
17
+ API / ``law.cornell.edu`` over the network (httpx, 30s timeout). Results are memoized on
18
+ the turn's :class:`LiiContext` so retries within a turn don't re-fetch.
19
+ * **Same contract as agent_tools.** Every tool returns a JSON-serializable dict; failures
20
+ come back as ``{"error": ...}`` so the model can recover. Outputs are bounded.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from dataclasses import dataclass, field
26
+ from typing import Callable
27
+
28
+ from webapp.agent_loop import Toolkit
29
+ from webapp.agent_tools import Tool, _clip, observation_text
30
+
31
+ # Output caps β€” keep any single observation small enough to feed back into an 8K ctx.
32
+ _MAX_RESULTS = 8 # eCFR search hits returned to the model
33
+ _EXCERPT_CHARS = 400 # per-hit excerpt slice
34
+
35
+
36
+ @dataclass
37
+ class LiiContext:
38
+ """Context for the LII tools. Unlike the packet agent there is no ``upload_id``; the
39
+ only state is an optional per-turn cache so repeated network lookups are free."""
40
+
41
+ _cache: dict = field(default_factory=dict)
42
+
43
+
44
+ # --------------------------------------------------------------------------- #
45
+ # Small helpers
46
+ # --------------------------------------------------------------------------- #
47
+ def _cached(ctx: LiiContext, key: tuple, fn: Callable[[], object]) -> object:
48
+ """Memoize a (possibly networked) lookup on the turn's context cache."""
49
+ cache = ctx._cache
50
+ if key not in cache:
51
+ cache[key] = fn()
52
+ return cache[key]
53
+
54
+
55
+ def _need(value, name: str) -> str:
56
+ """Coerce a required scalar arg to a non-empty string or raise ``ValueError``."""
57
+ s = str(value).strip() if value is not None else ""
58
+ if not s:
59
+ raise ValueError(f"Missing required argument '{name}'.")
60
+ return s
61
+
62
+
63
+ # --------------------------------------------------------------------------- #
64
+ # Tools
65
+ # --------------------------------------------------------------------------- #
66
+ def _search_regulations(ctx: LiiContext, query: str = "", limit: int = _MAX_RESULTS) -> dict:
67
+ from cornell_lii.client import HttpError
68
+ from cornell_lii.ecfr import search_federal
69
+
70
+ q = _need(query, "query")
71
+ try:
72
+ n = min(max(int(limit), 1), _MAX_RESULTS)
73
+ except (TypeError, ValueError):
74
+ n = _MAX_RESULTS
75
+ try:
76
+ hits = _cached(ctx, ("search", q, n), lambda: search_federal(q, limit=n))
77
+ except HttpError as e:
78
+ return {"error": f"eCFR search failed: {e}"}
79
+ results = [
80
+ {
81
+ "citation": h.get("citation"),
82
+ "label": h.get("label"),
83
+ "url": h.get("url"),
84
+ "excerpt": _clip(h.get("excerpt") or "", _EXCERPT_CHARS),
85
+ }
86
+ for h in hits
87
+ ]
88
+ return {"query": q, "count": len(results), "results": results}
89
+
90
+
91
+ def _resolve_cfr(
92
+ ctx: LiiContext,
93
+ citation: str | None = None,
94
+ title: str | None = None,
95
+ section: str | None = None,
96
+ verify: bool = True,
97
+ ) -> dict:
98
+ from cornell_lii.citations import CitationError, parse_cfr
99
+ from cornell_lii.client import HttpError
100
+ from cornell_lii.ecfr import verify_cfr
101
+ from cornell_lii.urls import cfr_section_url
102
+
103
+ try:
104
+ if citation:
105
+ cite = parse_cfr(citation)
106
+ title, section = cite.title, cite.section
107
+ else:
108
+ title, section = _need(title, "title"), _need(section, "section")
109
+ except (CitationError, ValueError) as e:
110
+ return {"error": str(e)}
111
+
112
+ out: dict = {
113
+ "citation": f"{title} CFR {section}",
114
+ "title": title,
115
+ "section": section,
116
+ "url": cfr_section_url(title, section),
117
+ }
118
+ if verify:
119
+ try:
120
+ v = _cached(ctx, ("verify_cfr", title, section), lambda: verify_cfr(title, section))
121
+ out.update(verified=v["valid"], heading=v["heading"], date=v["date"])
122
+ if not v["valid"] and v.get("detail"):
123
+ out["detail"] = v["detail"]
124
+ except HttpError as e:
125
+ out["verified"] = None
126
+ out["detail"] = f"eCFR verify failed: {e}"
127
+ return out
128
+
129
+
130
+ def _resolve_usc(
131
+ ctx: LiiContext,
132
+ citation: str | None = None,
133
+ title: str | None = None,
134
+ section: str | None = None,
135
+ verify: bool = True,
136
+ ) -> dict:
137
+ from cornell_lii.citations import CitationError, parse_usc
138
+ from cornell_lii.client import url_exists
139
+ from cornell_lii.urls import usc_section_url
140
+
141
+ try:
142
+ if citation:
143
+ cite = parse_usc(citation)
144
+ title, section = cite.title, cite.section
145
+ else:
146
+ title, section = _need(title, "title"), _need(section, "section")
147
+ except (CitationError, ValueError) as e:
148
+ return {"error": str(e)}
149
+
150
+ url = usc_section_url(title, section)
151
+ out: dict = {
152
+ "citation": f"{title} USC {section}",
153
+ "title": title,
154
+ "section": section,
155
+ "url": url,
156
+ }
157
+ if verify:
158
+ out["verified"] = _cached(ctx, ("usc_exists", url), lambda: url_exists(url))
159
+ return out
160
+
161
+
162
+ def _browse_cfr(ctx: LiiContext, title: str = "", part: str | None = None) -> dict:
163
+ from cornell_lii.urls import cfr_part_url, cfr_title_url
164
+
165
+ try:
166
+ t = _need(title, "title")
167
+ except ValueError as e:
168
+ return {"error": str(e)}
169
+ if part:
170
+ p = str(part).strip()
171
+ return {"citation": f"{t} CFR Part {p}", "url": cfr_part_url(t, p)}
172
+ return {"citation": f"{t} CFR", "url": cfr_title_url(t)}
173
+
174
+
175
+ def _state_materials(ctx: LiiContext, state: str = "") -> dict:
176
+ from cornell_lii.states import resolve_state
177
+ from cornell_lii.urls import state_portal_url, state_regs_url
178
+
179
+ try:
180
+ slug = resolve_state(_need(state, "state"))
181
+ except ValueError as e:
182
+ return {"error": str(e)}
183
+ return {
184
+ "state": slug.replace("_", " ").title(),
185
+ "slug": slug,
186
+ "portal_url": state_portal_url(slug),
187
+ "regs_url": state_regs_url(slug),
188
+ }
189
+
190
+
191
+ # --------------------------------------------------------------------------- #
192
+ # Registry, catalog, dispatch
193
+ # --------------------------------------------------------------------------- #
194
+ TOOLS: list[Tool] = [
195
+ Tool(
196
+ name="search_regulations",
197
+ description="Full-text search the federal Code of Federal Regulations (eCFR) and "
198
+ "get matching sections as Cornell LII links with short excerpts. Use this first "
199
+ "for topic questions when you don't already have a citation.",
200
+ parameters={
201
+ "type": "object",
202
+ "properties": {
203
+ "query": {"type": "string", "description": "Search terms, e.g. 'sexual harassment'."},
204
+ "limit": {"type": "integer", "description": f"Max hits (1-{_MAX_RESULTS}). Default {_MAX_RESULTS}."},
205
+ },
206
+ "required": ["query"],
207
+ },
208
+ run=_search_regulations,
209
+ ),
210
+ Tool(
211
+ name="resolve_cfr",
212
+ description="Resolve a federal regulation (CFR) citation to its Cornell LII page "
213
+ "and (by default) verify it exists via eCFR, returning the section heading. Pass "
214
+ "either a full 'citation' (e.g. '29 CFR 1604.11') or 'title' + 'section'.",
215
+ parameters={
216
+ "type": "object",
217
+ "properties": {
218
+ "citation": {"type": "string", "description": "Full citation, e.g. '29 CFR 1604.11'."},
219
+ "title": {"type": "string", "description": "CFR title number, e.g. '29'."},
220
+ "section": {"type": "string", "description": "Section, e.g. '1604.11'."},
221
+ "verify": {"type": "boolean", "description": "Confirm via eCFR (default true)."},
222
+ },
223
+ },
224
+ run=_resolve_cfr,
225
+ ),
226
+ Tool(
227
+ name="resolve_usc",
228
+ description="Resolve a US Code (federal statute) citation to its Cornell LII page "
229
+ "and (by default) verify the page resolves. Pass either a full 'citation' (e.g. "
230
+ "'42 USC 1983') or 'title' + 'section'.",
231
+ parameters={
232
+ "type": "object",
233
+ "properties": {
234
+ "citation": {"type": "string", "description": "Full citation, e.g. '42 USC 1983'."},
235
+ "title": {"type": "string", "description": "USC title number, e.g. '42'."},
236
+ "section": {"type": "string", "description": "Section, e.g. '1983'."},
237
+ "verify": {"type": "boolean", "description": "Confirm the LII page exists (default true)."},
238
+ },
239
+ },
240
+ run=_resolve_usc,
241
+ ),
242
+ Tool(
243
+ name="browse_cfr",
244
+ description="Get the Cornell LII browse link for a whole CFR title, or a part "
245
+ "within it. Use when the user wants the index/part rather than a single section.",
246
+ parameters={
247
+ "type": "object",
248
+ "properties": {
249
+ "title": {"type": "string", "description": "CFR title number, e.g. '29'."},
250
+ "part": {"type": "string", "description": "Optional part number, e.g. '1604'."},
251
+ },
252
+ "required": ["title"],
253
+ },
254
+ run=_browse_cfr,
255
+ ),
256
+ Tool(
257
+ name="state_materials",
258
+ description="Get Cornell LII links for a US state's legal materials: the state "
259
+ "portal page and its LII-hosted administrative code. Accepts a state name or USPS "
260
+ "abbreviation (e.g. 'Maine' or 'ME').",
261
+ parameters={
262
+ "type": "object",
263
+ "properties": {
264
+ "state": {"type": "string", "description": "State name or USPS abbreviation."},
265
+ },
266
+ "required": ["state"],
267
+ },
268
+ run=_state_materials,
269
+ ),
270
+ ]
271
+
272
+ _BY_NAME = {t.name: t for t in TOOLS}
273
+
274
+ # final_answer is special-cased by the loop (it ends the turn), but advertised in the
275
+ # catalog so the model sees it alongside the real tools.
276
+ FINAL_ANSWER = "final_answer"
277
+
278
+
279
+ def tool_catalog() -> list[dict]:
280
+ """OpenAI-style ``{name, description, parameters}`` schema for every LII tool, plus
281
+ the terminal ``final_answer`` β€” what the agent loop shows the model."""
282
+ cat = [
283
+ {"name": t.name, "description": t.description, "parameters": t.parameters}
284
+ for t in TOOLS
285
+ ]
286
+ cat.append(
287
+ {
288
+ "name": FINAL_ANSWER,
289
+ "description": "Give the user your final answer and end the turn. Use this as "
290
+ "soon as you have enough to answer.",
291
+ "parameters": {
292
+ "type": "object",
293
+ "properties": {
294
+ "answer": {"type": "string", "description": "The answer, in markdown."}
295
+ },
296
+ "required": ["answer"],
297
+ },
298
+ }
299
+ )
300
+ return cat
301
+
302
+
303
+ def run_tool(name: str, args: dict, ctx: LiiContext) -> dict:
304
+ """Dispatch one LII tool call. Returns a JSON-serializable result dict (always β€” a
305
+ failed/unknown call comes back as ``{"error": ...}`` so the model can recover)."""
306
+ tool = _BY_NAME.get(name)
307
+ if tool is None:
308
+ return {"error": f"Unknown tool '{name}'. Available: {', '.join(_BY_NAME)}."}
309
+ if not isinstance(args, dict):
310
+ return {"error": "Tool args must be a JSON object."}
311
+ try:
312
+ return tool.run(ctx, **args)
313
+ except TypeError as e:
314
+ return {"error": f"Bad arguments for '{name}': {e}"}
315
+ except Exception as e: # noqa: BLE001
316
+ return {"error": f"Tool '{name}' failed: {type(e).__name__}: {e}"}
317
+
318
+
319
+ def result_summary(tool: str, result: dict) -> str:
320
+ """A one-line, human-readable gist of a tool result for the live UI (raw JSON stays
321
+ available behind a disclosure). Best-effort β€” empty string when nothing fits."""
322
+ if not isinstance(result, dict):
323
+ return ""
324
+ if result.get("error"):
325
+ return f"error: {str(result['error'])[:80]}"
326
+ if isinstance(result.get("count"), int):
327
+ n = result["count"]
328
+ return f"{n} result{'' if n == 1 else 's'}"
329
+ if "verified" in result:
330
+ cite = result.get("citation") or "citation"
331
+ verified = result["verified"]
332
+ state = "verified" if verified else ("unverified" if verified is False else "link ready")
333
+ return f"{cite} Β· {state}"
334
+ if result.get("url"):
335
+ return result.get("citation") or "link ready"
336
+ if result.get("portal_url"):
337
+ return result.get("state") or "links ready"
338
+ return ""
339
+
340
+
341
+ def _system_prompt(ctx: LiiContext) -> str:
342
+ import json
343
+
344
+ catalog = json.dumps(tool_catalog(), ensure_ascii=False, indent=2)
345
+ return (
346
+ "You are the Cornell LII legal-research agent. You help the user find and link US "
347
+ "federal and state law β€” federal regulations (CFR), federal statutes (US Code), and "
348
+ "state legal materials β€” using the Cornell Legal Information Institute and the "
349
+ "public eCFR API.\n\n"
350
+ "You work by calling tools, one at a time, and reasoning over what they return. For "
351
+ "topic questions with no citation in hand, start with search_regulations; when you "
352
+ "have a citation, use resolve_cfr / resolve_usc to link and verify it.\n\n"
353
+ "Available tools (JSON Schema):\n" + catalog + "\n\n"
354
+ "PROTOCOL β€” follow exactly:\n"
355
+ "- Respond with a SINGLE JSON object and nothing else (no prose, no code fence).\n"
356
+ '- Shape: {"thought": "<one short sentence>", "tool": "<tool name>", "args": {<args>}}\n'
357
+ "- Call exactly one tool per step. Read its result, then decide the next step.\n"
358
+ f'- When you can answer, call "{FINAL_ANSWER}" with an "answer" in markdown.\n'
359
+ "- If a tool returns an error, adjust your args or try another tool.\n\n"
360
+ "IMPORTANT β€” what you can and cannot do:\n"
361
+ "- You return CITATIONS, official Cornell LII links, and SHORT eCFR search excerpts. "
362
+ "You do NOT have the full statutory or regulatory text. Never invent or paraphrase "
363
+ "legal text you have not seen in a tool result.\n"
364
+ "- Every legal claim in your answer must point to a citation/link you obtained from a "
365
+ "tool. Prefer verified citations; if a citation could not be verified, say so.\n"
366
+ "- Close with a brief attribution: legal text is hosted by Cornell LII "
367
+ "(law.cornell.edu); eCFR data is public domain."
368
+ )
369
+
370
+
371
+ # The toolkit the loop plugs in for the Cornell LII agent.
372
+ TOOLKIT = Toolkit(
373
+ system_prompt=_system_prompt,
374
+ run_tool=run_tool,
375
+ observation_text=observation_text,
376
+ result_summary=result_summary,
377
+ final_answer=FINAL_ANSWER,
378
+ )
webapp/local_llm.py CHANGED
@@ -395,3 +395,21 @@ def gpu_agent_turn(
395
  complete = _make_completer(llm)
396
  ctx = ToolContext(upload_id=upload_id, complete=complete)
397
  yield from agent_turn(messages, ctx, complete, max_steps=AGENT_MAX_STEPS)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
395
  complete = _make_completer(llm)
396
  ctx = ToolContext(upload_id=upload_id, complete=complete)
397
  yield from agent_turn(messages, ctx, complete, max_steps=AGENT_MAX_STEPS)
398
+
399
+
400
+ @spaces.GPU(duration=AGENT_DURATION)
401
+ def gpu_lii_agent_turn(messages: list[dict], model: str = "") -> Iterator[dict]:
402
+ """Run one Cornell LII legal-research turn inside a single GPU window.
403
+
404
+ Parallel to :func:`gpu_agent_turn` but with the LII toolkit and no uploaded packet β€”
405
+ the tools query the eCFR API / Cornell LII over the network rather than the GPU, so
406
+ the loaded GGUF is used only for the agent's reasoning. Yields the loop's frames
407
+ straight through (see :func:`webapp.agent_loop.agent_turn`).
408
+ """
409
+ from webapp.agent_loop import agent_turn
410
+ from webapp.lii_tools import TOOLKIT, LiiContext
411
+
412
+ llm = _load_llama(_available_model(model))
413
+ complete = _make_completer(llm)
414
+ ctx = LiiContext()
415
+ yield from agent_turn(messages, ctx, complete, max_steps=AGENT_MAX_STEPS, toolkit=TOOLKIT)
webapp/server.py CHANGED
@@ -62,6 +62,7 @@ server.api(backend.generate_agenda_report, name="report")
62
  server.api(backend.generate_agenda_item_report, name="item_report")
63
  server.api(backend.agenda_item_pages, name="item_pages")
64
  server.api(backend.agent_chat, name="agent")
 
65
 
66
 
67
  # Uploading the Agenda Packet PDF. A plain FastAPI multipart route, NOT a Gradio API
 
62
  server.api(backend.generate_agenda_item_report, name="item_report")
63
  server.api(backend.agenda_item_pages, name="item_pages")
64
  server.api(backend.agent_chat, name="agent")
65
+ server.api(backend.lii_agent_chat, name="lii_agent")
66
 
67
 
68
  # Uploading the Agenda Packet PDF. A plain FastAPI multipart route, NOT a Gradio API