Deploy Agenda Parser
Browse files- cornell_lii/__init__.py +16 -0
- cornell_lii/__main__.py +7 -0
- cornell_lii/citations.py +67 -0
- cornell_lii/cli.py +213 -0
- cornell_lii/client.py +50 -0
- cornell_lii/ecfr.py +96 -0
- cornell_lii/output.py +87 -0
- cornell_lii/states.py +43 -0
- cornell_lii/urls.py +99 -0
- webapp/agent_loop.py +47 -7
- webapp/backend.py +50 -0
- webapp/frontend/dist/assets/{index-ihZX68Cf.js β index-y7Mf8pNK.js} +0 -0
- webapp/frontend/dist/index.html +1 -1
- webapp/lii_tools.py +378 -0
- webapp/local_llm.py +18 -0
- webapp/server.py +1 -0
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:
|
| 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
|
|
|
|
|
|
|
| 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 |
-
|
|
|
|
| 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 ==
|
| 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":
|
| 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-
|
| 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
|