Unfortunately I don’t know of any way to read this year’s ICAIL papers, even through a library, other than requesting access to the preprint. But I’d still like to comment about the paper a little because I think of answer set programming as a slightly enigmatic and under-documented part of the Python world, but still one that could be promising for legal analysis. The logic program from the paper is on GitHub.

The answer set program in the Dix and Markovich paper defines a model in which a set of judges can each determine “each parent’s properties, whether these are relevant, if so, whether they are positive or negative, and how relevant these properties are.” The conclusions that the “judges” reach in the program are defeasible, which means the model can reach a conclusion based on incomplete information, and that adding new facts to the model can change the conclusion. The paper gives the example of reaching a conclusion on child custody in the mother’s favor, but then adding the fact “the mother is in jail” to change the outcome.

The ASP system supports both strong and weak negation, represented by a minus sign and the word “not” respectively. The paper suggests that these forms of negation should be used to represent the concepts “a judge has stated that a fact is false” and “a judge has not stated that a fact is true.” Apparently, because the formal logic statements include a reference to the judge, it’s possible to use some “negation” statements to describe the point of view of one judge, while using other negation statements for other judges. I wasn’t really able to understand the paper well enough to know if this is viable or not, but it seems odd. It’s easier for me to imagine the negation operators creating statements like “it’s false that the judge has stated that the fact is true” and “it’s not known that the judge has stated that the fact is true.”

I think the “judges” in the ASP system should be thought of as agents in a very abstract simulation, so the model doesn’t include a very complete depiction of the actions a judge might take in real life. But the paper does describe a way for one “judge” to be considered the “appellate judge” that “reviews” the decisions of the other judges.

Whether or not this model is adequate to describe what happens in real courtrooms, I think there’s a lot of potential in using answer set programming to discover possible outcomes given a set of legal “facts” or “statements”. The most accessible presentation I’ve seen about using solvers in Python (not specific to the legal domain) was Raymond Hettinger’s PyCon talk “Modern solvers: Problems well-defined are problems solved” (presentation at https://rhettinger.github.io/). But even that deals primarily with SAT solvers, not ASP solvers.

I’m left with a few questions:

• How can legal analysts put themselves in enough of a “logic programming” mindset to recognize when solvers are a good solution for a problem?

• Does legal procedure require so many changes of frame of reference that it can’t usefully fit into a logic programming model?

• Can we break down small parts of legal analysis tasks to be handled with solvers, while still doing most of our data modeling with traditional imperative programming (preferably in Python)?

CATLEX relies on a corpus of disability-claim decisions issued by the Board of Veterans’ Appeals, which was assembled by the Research Laboratory for Law, Logic and Technology (LLT Lab) at Hofstra. CATLEX was presented by Hannes Westermann, and the other two authors of the conference paper were Vern Walker of the LLT Lab, and Jaromir Savelka.

The project depended on a description of the elements of a claim of a service-related disability, in the form of a JSON “rule tree” that I think was created entirely by hand. Then the authors used the litellm Python client to present LLMs, including Claude 3.5 Sonnet, with Board decisions from the LLT Lab’s collection. The LLMs were prompted to determine whether the Board of Veterans’ Appeals found each element to be present or absent in each case. The Board’s determinations could then be plotted onto a diagram showing the steps needed to establish the claim, along with the LLM’s explanations of its interpretations of the Board’s reasoning. The screenshots of the resulting Vue app are neat-looking, but I’m not posting them because the paper is still a preprint and I don’t think the authors have published the screenshots online. Probably the screenshots could be replicated by running the code in the GitHub repo linked above.

The model may oversimplify somewhat, in condensing the range of possible decisions on a factor to just “True” or “False”. In the example data, when the Board assumed a factor was satisfied, that was considered “True”. When the Board didn’t mention a factor, that was considered “False”.

I think CATLEX’s rule visualization by itself could be an interesting avenue for future open source tools, even if the content was created by hand. And the LLM data extraction is also exciting, since it shows how researchers are starting to break down judicial reasoning into modular parts, assigning some of those parts to AI agents, and measuring the accuracy of the results. But in this project the AI hasn’t fully taken over, since the legal analysis is still tethered to human annotations describing the structure of a very specific legal issue.

I thought CollateX’s out-of-the-box “html” mode visualization was potentially useful. In this case it might help readers notice that while the Supreme Court said a certain “argument” was not a basis for overruling a holding, one of the lower courts restated this to assert that an “error” was not a basis for overruling.

Here’s the table CollateX produced to compare the three passages.

I thought the “svg” and “svg_simple” modes were not very readable, because they were a little too chaotic and cluttered with arrows and labels. I didn’t find any option for the svg charts to be vertically oriented, so even with this relatively short text I got an extremely wide image, which Jupyter and Jekyll both wanted to shrink down to an unreadable size.

(CollateX also has an “html2” mode that uses eyeball-melting background colors to “draw your attention” to cells containing unique text.)

CollateX has a “fuzzy” matching mode, where similar strings can be shown side-by-side in the visualization. However, the fuzzy mode is only available when CollateX is set to put only a single word or “token” in each cell of the table, which seems like it would be far less readable. There are also JSON and XML output modes that could be used to export the data to alternate visualization tools.

The primary use case of CollateX is comparing alternate versions of the same work, which is not exactly what I did here. While a later court opinion might choose to restate a significant passage from an earlier opinion, it might also insert commentary or quote parts of the earlier opinion out of order. If the two texts aren’t intended to be the same, then it may not be useful for a collation to show that there are lots of differences. To determine whether it’s appropriate to show a text collation to a user, a publisher would need a reliable way of detecting situations where a later court is trying to restate a holding from an earlier opinion, but not using the exact same words.

CollateX is available under GNU General Public License v3.0.

Only a few of the research projects presented had code available to run in Python. Out of those that did, I think the standout was a Legal Case-Based Reasoning system presented by Daphne Odekerken of Utrecht University. The paper was coauthored with Floris Bex and Henry Prakken, and it also cited inspiration from formal logic models of precedent developed by John Horty.

The Python package, which is just named with the initials LCBR, lets users define a legal issue and a list of factors that contribute to determining the issue’s outcome. A factor’s value can be set as a boolean, or as a number in a range. For instance, the demo application is about whether a retail sales website should be investigated as fraudulent. Boolean factors include whether the site has a terms and conditions page, and whether it has a non-functioning payment link. Numeric factors include the number of days the page has been online. If I understand right, setting up a user application with the package requires identifying the full list of factors that can be used to decide the legal issue, and also requires labeling each of the factors and “pro” or “contra”. For instance, the number of days online would be a “contra” factor where the website becomes less suspicious the longer it’s been online. I don’t think there’s any way to say that a “pro” factor can become a “contra” factor in the presence of specific other factors, so the system would only work when every factor has a certain polarity that never changes.

One great feature of LCBR is that it might not require you to have all the possible information about a particular case before you can get an answer about the outcome. If there’s no possible factor that will distinguish your case from other cases that reached a certain outcome, then the system can reach a stable conclusion that the same outcome will be reached even if new information is added later. For example, if there’s no way the facts of the current case can turn out to be more favorable to the defendant on any dimension compared to the facts of a prior case that reached a decision against a defendant, then the system reasons that the current case will go against the defendant as well. As that example suggests, LCBR does assume that all the cases in the database are consistent with one another. If not enough factors have been determined to reach a stable conclusion, LCBR also has an algorithm to determine which other factors are most relevant to decide the issue. This seems similar to the function that Docassemble uses to determine which question to present to the user next during a guided interview.

The LCBR package has a UI that can be spun up using Flask and Dash, but I wouldn’t exactly call it user-friendly because it seems to assume the user has a lot of knowledge about the theoretical concepts that inform the case-based reasoning algorithm. However, a version of the same tool was used to create a user-facing intake system for the National Police AI Lab of the Netherlands.

I’d love to see a system like LCBR expanded beyond its current limitations. When creating a model of a legal issues, I’d prefer not to have to list all factors that can bear on a determination in advance, because sometimes newly-added cases will also identify new factors. I’d also prefer not to have to identify the polarity of every factor in advance. Even the paper introducing LCBR concedes that the assumption of a consistent case base is “quite a strong assumption.” Instead of making that assumption, I’d like to use a system that can provide rules of precedent that start with an inconsistent set of cases, and then show how certain cases can be overruled or disregarded until all the cases that remain are consistent. (But when I suggest features like that, I’m thinking of what would be useful for simulating common law jurisprudence, which probably wouldn’t meet the needs of government agencies in the Netherlands.) And finally, instead of having models of “cases” covering only one legal issue, it would be nice to model a collection of rules showing ways to reach multiple legal conclusions, some of which are factors potentially supporting further conclusions. That would allow the system to evolve beyond simple one-step legal determinations such as whether to open a fraud investigation, so that the system could model more complex processes such as litigation.

Basically, I became tired of the proliferation of messy data loading code in the AuthoritySpoke repository. That repository was the core of my “legal rule automation” project, but it was beginning to look like a cluttered workshop full of odds and ends. Every time a part of AuthoritySpoke started to look neat and coherent, I bundled it up as a separate Python package with separate documentation and moved it to a separate GitHub repository, leaving behind the messier code that didn’t quite fit together or that was hard to use.

When I created the judicial opinion download library Justopinion, I was able to choose a serializer without the burden of supporting legacy code, and Pydantic felt like the right choice, so I went with it. But then Justopinion became a dependency of AuthoritySpoke, which meant AuthoritySpoke had to import Pydantic to run. That put me on the path to adopting Pydantic for the entire AuthoritySpoke project.

The major design difference between Pydantic and the serializer I previously used, Marshmallow, is that with Pydantic the information needed to serialize objects to JSON is stored on the objects themselves, rather than in separate serializer classes. The result was that I was also able to delete a lot of old code I’d written, including several whole modules, and replace it with Pydantic’s built-in functionality.

My biggest fear about the transition was that because I’d have to make changes to all the Python classes in my project that stored data, the change might introduce bugs that I wouldn’t be able to fix, and the migration to Pydantic would simply fail. But in the end I was able to migrate every feature to Pydantic, while removing both Marshmallow and its associated API documentation library Apispec from the list of dependencies that have to be imported when AuthoritySpoke is installed.

The new version 0.9 of AuthoritySpoke has been mainly about reducing the amount of code and improving its organization, without introducing many new features. But as a result of the Pydantic transition, nearly all AuthoritySpoke classes have newly-added .dict() and .json() methods for serializing to generic datatypes, as well as .schema() and .schema_json() methods for generating JSON Schema API documentation. These serialization methods are easier to use and understand than the alternatives that existed in the past. Overall, version 0.9 is more consistent, more maintainable, less buggy, and more suitable for larger projects.

In the years since the API launched, it’s become significantly more useful with the addition of citation graph data. But it’s also important to recognize the limits on the API’s scope: it only includes cases published in print, and only cases published in bound volumes through 2018, when the scanning project took place. The API also limits public users to 500 API calls per day for most jurisdictions.

I created a Python module called Justopinion with a few utility functions for getting opinions from the Caselaw Access Project API. It’s mostly designed around the use case of downloading a judicial decision with a known citation, getting the text of the opinions in the case, and then downloading any other decisions cited within those opinions.

Here’s an example from Justopinion’s getting started guide that roughly follows that workflow:

from justopinion import CAPClient
client = CAPClient(api_token=CAP_API_KEY)
thornton = client.read_cite("1 Breese 34", full_case=True)

The text that gets passed to the CAPClient.read_cite method (such as “1 Breese 34”) can be normalized as a recognizable citation thanks to the Eyecite package from the Free Law Project.

thornton.casebody.data.parties[0]
'John Thornton and others, Appellants, v. George Smiley and John Bradshaw, Appellees.'

The case is loaded as a Pydantic model, so any static analysis tools you use on your Python code should understand the data types for each field. The case.law API documentation describes what you should expect the API to deliver.

len(thornton.cites_to)
1
str(thornton.cites_to[0])
'Citation to 15 Ill., 284'

We can see that Thornton v. Smiley cites to only one other case. By passing the citation to the CAPClient.read_cite method, we can download JSON representing the cited decision and turn it into another instance of the Decision class.

cited = client.read_cite(thornton.cites_to[0], full_case=True)
str(cited)
'Marsh v. People, 15 Ill. 284 (1853-12-01)'

We can also locate text within an opinion we downloaded, and generate an Anchorpoint selector to reference a passage from the opinion.

thornton.opinions[0].locate_text("The court knows of no power in the administrator")
TextPositionSet{TextPositionSelector[22, 70)}

Of course, Justopinion isn’t necessary for accessing the Case Access Project API from Python. The API’s documentation gives this example of downloading a case using requests, which is a more flexible option but it might involve writing more code in some situations.

response = requests.get(
    'https://api.case.law/v1/cases/435800/?full_case=true',
    headers={'Authorization': 'Token abcd12345'}
)

Justopinion originated as part of my other Python library AuthoritySpoke, and as of AuthoritySpoke version 0.8, Justopinion is a dependency that gets imported as part of AuthoritySpoke’s setup process. Justopinion is still in an early state, and there are lots of features that could still be added. I decided to use the generic name Justopinion instead of naming the package after the CAP API because I’m considering also adding support for the CourtListener API, and possibly some use cases that don’t depend on an API. If you have any comments or requests about Justopinion, pleases post them at its GitHub repo.

Like most Docassemble extensions, Docassemble-L4 uses Python code to create an interactive interview to help apply a legal standard to a user’s fact pattern. What makes Docassemble-L4 unique is that it lets you create that Python code by translating it automatically from a different language called s(CASP), which appears to be closely related to Prolog. The intended way to get that S(CASP) code is by translating it automatically from L4. I understand L4 is a programming language that hasn’t been released yet, but it will leverage the Z3 theorem prover. To use Docassemble-L4, you must provide not just the s(CASP) code, but also a YAML document in a special format called LExSIS (no relation to the legal publisher), which tells Docassemble how to create an interview interface to elicit information relevant to the declarative logic statements in the s(CASP) code.

And the data input syntax is verbose. It suffers from a degree of combinatorial explosion since s(CASP)’s inference rules don’t seem to have a proper “or” syntax, as shown in this excerpt from the example data:

business_entity(X) :- carries_on(X,Y), business(Y), company(X), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).
business_entity(X) :- carries_on(X,Y), business(Y), corporation(X), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).
business_entity(X) :- carries_on(X,Y), business(Y), partnership(X), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).
business_entity(X) :- carries_on(X,Y), business(Y), llp(X), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).
business_entity(X) :- carries_on(X,Y), business(Y), soleprop(X), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).
business_entity(X) :- carries_on(X,Y), business(Y), business_trust(X), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).
business_entity(X) :- carries_on(X,Y), business(Y), not law_practice_in_singapore(X), not joint_law_venture(X), not formal_law_alliance(X), not foreign_law_practice(X), not third_schedule_institution(X).

So Docassemble-L4 is very challenging to use. But still, it’s a significant accomplishment because it moves Docassemble farther from single-purpose interviews, and toward generating conclusions by searching a large collection of legal rules derived from legislation. This is the same idea suggested by the Best Practices section of the Docassemble documentation, which suggests distributing the “mandatory” block that defines the objective of a particular interview separately from the file that defines the rest of the rules, so that the parts of the interview that are more likely to be reusable are easy to find in a separate module. Another benefit of Docassemble-L4’s roots in logic programming is that it can generate explanations for its conclusions, with links to the relevant passages of legislation. Maybe more of Docassemble-L4’s workflow can be automated in future versions.

Although I’ve been critical enough already, I have one more quibble with Docassemble-L4’s design philosophy. I think Docassemble-L4 was written with the idea that each rule written in s(CASP) will correspond to a separately-numbered section of the published legislation. I think that’s a little bit of an artificial restriction, and I think it resulted in the example data containing a lot of shorter rules connected by meta-rules about how one rule “overrides” another. If instead the legislation was thought of as containing larger rules that could span multiple numbered paragraphs, it would no longer look like there were so many contradictions within the same legal code, and there would be less need for the user to create meta-rules about which rules take precedence over others in the event of a conflict. A really expressive schema for legal analysis should include a rich syntax to describe the relationship between a legal rule and the legal documents that enable it.

I planned for AuthoritySpoke to load two kinds of data: machine-serialized JSON objects, and also handmade test data. I wanted this handmade data to allow various kinds of abbreviations, and even to be tolerant of certain kinds of errors. And then I made the fateful decision to create just one set of data loading schemas for loading both kinds of data. That was probably the most costly design mistake I’ve made on AuthoritySpoke (that I know of!) so far.

The functions that expanded abbreviated text in input files turned out to be easily the most finicky and error-prone parts of AuthoritySpoke. They also had a tendency to break in inscrutable ways when I modified functions in far-away parts of AuthoritySpoke that I had assumed were safely isolated from the text expansion functions. And they caused workflows that should have been simple to become lengthy and hard to debug. It was as if all the data that I loaded into AuthoritySpoke first had to be placed on a very long conveyor belt (or to be more literal, a very tall call stack) where the data would be poked and tweaked and adjusted by a long series of functions that corrected typos, expanded abbreviations, and the like. When something went wrong, I’d have to inspect all of the functions along the conveyor belt until I found the one that wasn’t working as designed. The Marshmallow data serialization library was permissive enough to let me introduce all kinds of anomalies into the data loading process, but in some ways I used that freedom to shoot myself in the foot. And of course, when I tried to use open source libraries to automatically generate a publishable OpenAPI specification by analyzing the schemas I’d written, the result made no sense because I’d used the serializers in nonstandard ways. (AuthoritySpoke’s current OpenAPI specification is better, I think.)

Also, the first process I established for loading handmade data was for the user to create a JSON file. But really, nobody wants to create JSON files by hand without purpose-built tools. So in version 0.7, my solution is to create a separate data loading workflow for handmade data, which should now be in YAML instead of in JSON. Here’s an example of a YAML file using the new data input format, with one of the rules from the “Beard Act” test dataset that I posted about before.

- holdings:
    - inputs:
        - type: fact
          content: "{the suspected beard} was facial hair"
        - type: fact
          content: the length of the suspected beard was >= 5 millimetres
        - type: fact
          content: the suspected beard occurred on or below the chin
      outputs:
        - type: fact
          content: the suspected beard was a beard
      enactments:
        - node: /test/acts/47/4
          exact:
            "In this Act, beard means any facial hair no shorter than 5 millimetres
            in length that: occurs on or below the chin"
      universal: true

(Nobody wants to create YAML files by hand either, but that’s a problem for another day.)

The YAML data loading module can now be kept separate from the rest of AuthoritySpoke, where it’ll be less likely to hurt anyone, and the workflow for loading data from JSON won’t include any features for handling abbreviations or typos. Most importantly for me, I’ll be able to write unit tests that get closer to isolating just the functions they’re really trying to test, without touching the text formatting functions.

I considered switching from Marshmallow to the trendier Pydantic serializer, but I decided against it for two related reasons. First, the AuthoritySpoke classes that represent units of legal analysis already have a very complicated subclass inheritance pattern. Pydantic requires any class that’s going to be serialized to also inherit from a Pydantic serialization parent class. I was afraid that inheriting another subclass would have added even more complexity that could have had unforeseen consequences. Second, I’ve had good experiences applying the design concept of dependency inversion. I want to think of serialization libraries as implementation details, not as core features of AuthoritySpoke. By sticking with Marshmallow, I can keep the serialization schemas in their own modules separate from the core business logic. The core modules of AuthoritySpoke don’t have to “know about” the serializer classes, and I can write unit tests for the core business logic that don’t touch Marshmallow in any way.

The biggest challenge remaining in AuthoritySpoke’s data schema (including the simpler non-YAML schema) is that it’s a polymorphic schema, meaning more than one object schema can occur in the same place. For instance, an “input” or “output” for AuthoritySpoke’s Holding class could be a Fact, or it could be an item of Evidence, or other things. In order to implement the feature of polymorphism, AuthoritySpoke needs to import not just Marshmallow but also a related library called marshmallow-oneofschema. I’ve learned that I should get nervous when I import a software package without a large and active community, and for me the easiest way to measure that community is GitHub stars, which basically correspond to satisfied users. Marshmallow has 5,500 stars, which is not that high compared to the 21,000 stars that its competitor Django Rest Framework has. (Pydantic has 6,500.) But if I want to generate an OpenAPI specification for my Marshmallow schema, I have to also download apispec, which has 859 stars at the time of writing. Then my polymorphic schema requires me to grab marshmallow-oneofschema, which has a mere 96 stars. And then the polymorphic part of my schema needs to be included in the OpenAPI specification too, so I have to import apispec-oneofschema, which has just eight stars including mine. Pretty scary. These libraries could have trouble in the future, and I expect to be relying on them a lot as I move forward with AuthoritySpoke.

The future of AuthoritySpoke depends on getting it working with web APIs. Not to mention a web user interface. Version 0.7 does a lot to simplify one of AuthoritySpoke’s data models to make it suitable for the web. An even simpler data model would be better, but I think the foundation exists to design ways to share and organize judicial rule models on authorityspoke.com.

Eyecite is built atop two arduous research projects that were themselves released as Python packages: Courts-DB and Reporters-DB. These provide the data that lets Eyecite know which strings are valid case citations, and what courts published the opinions at each citation. Courts-DB and Reporters-DB were also created by the Free Law Project, building on earlier work by Frank Bennett and the Legal Resource Registry.

I’ll use the rest of this blog post to try out Eyecite’s basic features and give my first impressions. Eyecite is still under active development and I’m testing the version on the current master branch, which isn’t an official release version so it could be extra-buggy.

Detecting Citations

I tested Eyecite’s citation detection feature on the first paragraph of the discussion section of the US Supreme Court’s recent opinion in Google v. Oracle America.

>>> import eyecite
text_from_opinion = """Copyright and patents, the Constitution says,
    are to “promote the Progress of Science and useful Arts,
    by securing for limited Times to Authors and Inventors the
    exclusive Right to their respective Writings and Discoveries.”
    Art. I, §8, cl. 8. Copyright statutes and case law have made
    clear that copyright has practical objectives. It grants an
    author an exclusive right to produce his work (sometimes for
    a hundred years or more), not as a special reward, but in order
    to encourage the production of works that others might reproduce
    more cheaply. At the same time, copyright has negative features.
    Protection can raise prices to consumers. It can impose special
    costs, such as the cost of contacting owners to obtain reproduction
    permission. And the exclusive rights it awards can sometimes stand
    in the way of others exercising their own creative powers. See
    generally Twentieth Century Music Corp. v. Aiken, 422 U. S. 151,
    156 (1975); Mazer v. Stein, 347 U. S. 201, 219 (1954)."""

Eyecite successfully discovered all three citations in the paragraph.

>>> citations = eyecite.get_citations(text_from_opinion)
>>> len(citations)
3

Eyecite also successfully found that the first citation wasn’t a citation to a case.

>>> citations[0]
NonopinionCitation(
    token=SectionToken(
        data='§8,',
        start=254,
        end=257),
    index=93,
    span_start=None,
    span_end=None)

The only slight problem was that Eyecite only found three characters of the Non-opinion citation. If I needed to exclude the Non-opinion citations from the text for some reason, it would have been better if it had found the full citation text “Art. I, §8, cl. 8”.

>>> citations[0].token.data
'§8,'

Eyecite identified the other two citations in the paragraph as case citations. It came up with an amazing amount of information about them, almost all of which looks correct (it only came up with “Corp.” for the plaintiff’s name).

>>> citations[1]
FullCaseCitation(
    token=CitationToken(
        data='422 U. S. 151',
        start=984,
        end=997,
        volume='422',
        reporter='U. S.',
        page='151',
        exact_editions=(),
        variation_editions=(
            Edition(
                reporter=Reporter(
                    short_name='U.S.',
                    name='United States Supreme Court Reports',
                    cite_type='federal',
                    is_scotus=True),
                short_name='U.S.',
                start=datetime.datetime(1875, 1, 1, 0, 0),
                end=None),),
        short=False,
        extra_match_groups={}),
    index=365,
    span_start=None,
    span_end=None,
    reporter='U.S.',
    page='151',
    volume='422',
    canonical_reporter='U.S.',
    plaintiff='Corp.',
    defendant='Aiken,',
    pin_cite='156',
    extra=None,
    court='scotus',
    year=1975,
    parenthetical=None,
    reporter_found='U. S.',
    exact_editions=(),
    variation_editions=(
        Edition(
            reporter=Reporter(
                short_name='U.S.',
                name='United States Supreme Court Reports',
                cite_type='federal',
                is_scotus=True),
            short_name='U.S.',
            start=datetime.datetime(1875, 1, 1, 0, 0), end=None),),
    all_editions=(
        Edition(
            reporter=Reporter(
                short_name='U.S.',
                name='United States Supreme Court Reports', cite_type='federal',
                is_scotus=True),
            short_name='U.S.',
            start=datetime.datetime(1875, 1, 1, 0, 0), end=None),),
    edition_guess=Edition(
        reporter=Reporter(
            short_name='U.S.',
            name='United States Supreme Court Reports', cite_type='federal',
            is_scotus=True),
        short_name='U.S.',
        start=datetime.datetime(1875, 1, 1, 0, 0),
        end=None)
    )

Of course, the court that issued the cited opinion, and the reporter where it was published, are identified correctly.

>>> citations[1].court
'scotus'
>>> citations[1].reporter
'U.S.'

Eyecite can’t extract the exact date of the cited case, but it can get the start and end dates for the reporter series where the case was published, and it can also get the year from the parenthetical in the citation.

>>> citations[1].year
1975

Cleaning up Opinion Text

It’s also worth noticing how Eyecite handles “Id.” citations. I grabbed a paragraph from the Facts section of Google v. Oracle America with an example of an “Id.” citation. But this time, because the text looks like it probably has a problem with line breaks or whitespace, I’ll also try out Eyecite’s utility function for cleaning up opinion text.

facts_section = """Google envisioned an Android platform that was free and
    open, such that software developers could use the tools
    found there free of charge. Its idea was that more and more
    developers using its Android platform would develop ever
    more Android-based applications, all of which would make
    Google’s Android-based smartphones more attractive to ultimate consumers.
    Consumers would then buy and use ever
    more of those phones. Oracle America, Inc. v. Google Inc.,
    872 F. Supp. 2d 974, 978 (ND Cal. 2012); App. 111, 464.
    That vision required attracting a sizeable number of skilled
    programmers.
    At that time, many software developers understood and
    wrote programs using the Java programming language, a
    language invented by Sun Microsystems (Oracle’s predecessor). 872 F. Supp. 2d, at 975, 977. About six million programmers had spent considerable time learning, and then
    using, the Java language. App. 228. Many of those programmers used Sun’s own popular Java SE platform to develop new programs primarily for use in desktop and laptop
    computers. Id., at 151–152, 200. That platform allowed
    developers using the Java language to write programs that
    were able to run on any desktop or laptop computer, regardless of the underlying hardware (i.e., the programs were in
    large part “interoperable”). 872 F. Supp. 2d, at 977. Indeed, one of Sun’s slogans was “‘write once, run anywhere.’”
    886 F. 3d, at 1186."""

To use the clean_text function, you pass a parameter containing the names of the cleaning functions you want to use.

>>> clean_facts_section = eyecite.clean_text(facts_section, ["all_whitespace"])

I can verify that the cleaning function removed some whitespace by comparing the length of the two text strings.

>>> len(facts_section) - len(clean_facts_section)
78

Handling Short and “Id.” Citations

Running the get_citations method again, I found that it discovered all 5 citations.

>>> facts_section_citations = eyecite.get_citations(clean_facts_section)
>>> len(facts_section_citations)
5

Eyecite has special ShortCitation and IdCitation classes that will capture all the information available from a citation even when it’s not a full citation. Eyecite’s string representation of the ShortCitation class still looks a little wonky in the version I’m testing…

>>> print(facts_section_citations[1])
None, 872 F. Supp. 2d, at 975

…but by looking at the token attribute I can see that Eyecite found a lot of useful information.

>>> facts_section_citations[1].token
CitationToken(
    data='872 F. Supp. 2d, at 975',
    start=757,
    end=780,
    volume='872',
    reporter='F. Supp. 2d',
    page='975',
    exact_editions=(
        Edition(
            reporter=Reporter(
                short_name='F. Supp.',
                name='Federal Supplement',
                cite_type='federal',
                is_scotus=False),
            short_name='F. Supp. 2d',
            start=datetime.datetime(1988, 1, 1, 0, 0),
            end=datetime.datetime(2014, 8, 21, 0, 0)),),
    variation_editions=(),
    short=True,
    extra_match_groups={})

In the short citation 872 F. Supp. 2d, at 975, 977, the start page of the cited opinion is omitted, but Eyecite has recognized the pin cite to two different pages.

>>> facts_section_citations[1].pin_cite
'975, 977'

The next citation is an “Id.” citation, which provides even less information than a ShortCitation.

>>> facts_section_citations[2]
Id., at 151

It looks like Eyecite wasn’t able to collect much from the “Id.” citation, other than the pin cite and the position of the citation in the text I provided.

>>> facts_section_citations[2].__dict__
{
    'token': IdToken(data='Id.,', start=1041, end=1045),
    'index': 310,
    'span_start': None,
    'span_end': 1052,
    'pin_cite': 'at 151'
}

It might look like we’re going to have to match that “Id.” citation to the case it references manually. But no! Eyecite has another trick up its sleeve. If we pass an ordered list of citations to Eyecite’s resolve_citations method, it’ll match up the Id. citation to the case cited by its antecedent citation.

>>> resolved_citations = eyecite.resolve_citations(facts_section_citations)

Basically, Eyecite will use the citations its recognizes to create Resource objects, and then those Resources become keys for a lookup table to get all the citations that match the same Resource. When you look up the correct Resource in resolved_citations, it gives you all the citations that refer to that Resource, including any “Id.” citations. I think this feature is still under development, and honestly I’d like to see more documentation about how to use it efficiently. But there are definitely great gains to be made from a tool that can understand “Id.” and “Supra” citations automatically.

Annotating Citations in Text

Eyecite’s annotate function method is exciting for anybody publishing caselaw online. It can add HTML links or other markup to the text that Eyecite just searched through for citations. CourtListener’s URL structure doesn’t seem to lend itself to automatically creating links, so instead I’ll give an example of automatically creating links to Harvard’s case.law website. I’ll start by getting a list of citations again.

>>> discussion_text = eyecite.clean_text(text_from_opinion, ["all_whitespace"])
>>> discussion_citations = eyecite.get_citations(discussion_text)

Next, I need a function that can generate the URL for a court opinion on case.law based on its CaseCitation object. Unfortunately Eyecite’s CaseCitation object doesn’t provide the same abbreviation style that case.law uses for the names of reporter volumes, so I had to add a mockup of a conversion table using the reporter_abbreviations variable. But the CaseCitation object does supply the volume and page fields for the reporter where the case is published, and the pin_cite field seems to be easy to transform into the format case.law needs.

import re
from urllib.parse import urlunparse, ParseResult
from eyecite.models import CaseCitation

def url_from_citation(cite: CaseCitation) -> str:
    """Make a URL for linking to an opinion on case.law."""
    reporter_abbreviations = {
        'U.S.': "us",
        "F. Supp.": "f-supp"
    }
    reporter = reporter_abbreviations[cite.canonical_reporter]

    if cite.pin_cite:
        # Assumes that the first number in the pin_cite field is
        # the correct HTML fragment identifier for the URL.
        page_number = re.search(r'\d+', cite.pin_cite).group()
        fragment = f"p{page_number}"
    else:
        fragment = ""

    url_parts = ParseResult(
        scheme='https',
        netloc='cite.case.law',
        path=f'/{reporter}/{cite.volume}/{cite.page}/',
        params='',
        query='',
        fragment=fragment)

    return urlunparse(url_parts)

>>> url_from_citation(citations[2])
'https://cite.case.law/us/347/201/#p219'

Now I can write a short function to make annotations in the the expected format, and then use Eyecite to insert these links in the text anywhere that Eyecite finds a case citation.

def make_annotations(
    citations: list[CaseCitation]) -> list[tuple[tuple[int, int], str, str]]:
    result = []
    for cite in citations:
        if isinstance(cite, CaseCitation):
            caselaw_url = url_from_citation(cite)
            result.append(
                (cite.span(),
                f'<a href="{caselaw_url}">',
                "</a>")
            )
    return result

>>> annotations = make_annotations(discussion_citations)
>>> annotated_text = eyecite.annotate(discussion_text, annotations)
>>> print(annotated_text)
Copyright and patents, the Constitution says, are to “promote the Progress of Science and useful Arts, by securing for limited Times to Authors and Inventors the exclusive Right to their respective Writings and Discoveries.” Art. I, §8, cl. 8. Copyright statutes and case law have made clear that copyright has practical objectives. It grants an author an exclusive right to produce his work (sometimes for a hundred years or more), not as a special reward, but in order to encourage the production of works that others might reproduce more cheaply. At the same time, copyright has negative features. Protection can raise prices to consumers. It can impose special costs, such as the cost of contacting owners to obtain reproduction permission. And the exclusive rights it awards can sometimes stand in the way of others exercising their own creative powers. See generally Twentieth Century Music Corp. v. Aiken, <a href="https://cite.case.law/us/422/151/#p156">422 U. S. 151</a>, 156 (1975); Mazer v. Stein, <a href="https://cite.case.law/us/347/201/#p219">347 U. S. 201</a>, 219 (1954).

We can see that the annotate function has inserted hyperlink markup around the citations near the end of the text passage. And by displaying the text as Markdown, we can verify that the generated links go to the right places on case.law.

>>> from IPython.display import display, Markdown
>>> display(Markdown(annotated_text))

Copyright and patents, the Constitution says, are to “promote the Progress of Science and useful Arts, by securing for limited Times to Authors and Inventors the exclusive Right to their respective Writings and Discoveries.” Art. I, §8, cl. 8. Copyright statutes and case law have made clear that copyright has practical objectives. It grants an author an exclusive right to produce his work (sometimes for a hundred years or more), not as a special reward, but in order to encourage the production of works that others might reproduce more cheaply. At the same time, copyright has negative features. Protection can raise prices to consumers. It can impose special costs, such as the cost of contacting owners to obtain reproduction permission. And the exclusive rights it awards can sometimes stand in the way of others exercising their own creative powers. See generally Twentieth Century Music Corp. v. Aiken, 422 U. S. 151, 156 (1975); Mazer v. Stein, 347 U. S. 201, 219 (1954).

Overall, Eyecite is a powerful tool with great potential to help the legal field gain the benefits of Python’s data analysis and data science ecosystem.

“Generic” in AuthoritySpoke

As mentioned before, the text of a Factor is like a phrase, and the terms of the Factor are like the nouns that function as the subject and objects of the phrase. If a Factor’s terms are labeled as “generic”, then the Factor can be considered to have the same meaning as another Factor that has different terms, as long as the other Factor’s terms are also labeled “generic”.

Here’s an example (based on the documentation for Nettlesome, which is a dependency of AuthoritySpoke). Each Entity object is “generic” by default, so all four of the “terms” in the example are considered “generic”. I’ve also given each Entity a generic-sounding name, instead of a proper noun, to emphasize that each Fact could refer to many different people. However, nothing in AuthoritySpoke will stop you from using proper nouns as the names of generic terms. All the examples in this article were tested on version 0.6.0 of AuthoritySpoke.

>>> from authorityspoke import Fact, Entity
>>> poet_payment = Fact("$payor made a payment to $payee",
...     terms=[Entity("the fierce philanthropist"), Entity("the starving poet")])
>>> henchman_payment = Statement("$payor made a payment to $payee",
...     terms=[Entity("the affable spy"), Entity("the devious henchman")])
>>> print(henchman_payment)
the statement that <the affable spy> made a payment to <the devious henchman>

The means() method can be used to determine whether two Facts have the same meaning.

>>> poet_payment.means(henchman_payment)
True

The explain_same_meaning() method generates an Explanation showing why the two Facts can be considered to have the same meaning.

>>> print(poet_payment.explain_same_meaning(henchman_payment))
"""Because <the fierce philanthropist> is like <the affable spy>, and <the starving poet> is like <the devious henchman>,
  the fact that <the fierce philanthropist> made a payment to <the starving poet>
MEANS
  the fact that <the affable spy> made a payment to <the devious henchman>"""

The illustration above shows that when AuthoritySpoke finds two Facts to be the same, it means that the relationships they describe are the same. It doesn’t at all mean that the identities of the “generic” Entities are the same.

Identifying Parallel Generic Terms

In AuthoritySpoke, the “context” of a comparison dictates which generic terms are considered parallel to one another. If no context parameter is passed in to a comparison method like .means(), then the comparison method will try every permutation of both Facts’ generic terms to find ways to match them all. Passing in a context parameter limits the ways that the generic terms can be matched.

In this example, the two Facts are compared in a context where it has been established that the philanthropist is more like the henchman, and the poet is more like the spy. (After all, to AuthoritySpoke these names are just strings, and AuthoritySpoke has no idea that they don’t sound similar.) To create this context, we pass in a tuple of two lists: a list of terms on the left that will be replaced, and a list of replacements from the right in the corresponding order. Because the context precludes the first term of poet_payment from being matched to the first term of henchman_payment, the method that checks whether these Facts have the same meaning now returns False.

>>> poet_payment.means(henchman_payment)
...     context=(
...         [Entity("the fierce philanthropist"), Entity("the starving poet")],
...         [Entity("the devious henchman"), Entity("the affable spy")])
...     )
False

Instead of using .means(), we could also have used the context parameter in the same format to test whether the first Factor .implies() or .contradicts() the other. There’s more information about using a context parameter with comparison methods in the Nettlesome documentation.

Using Context to Generalize Legal Holdings

Up to now, we’ve only compared Factors outside the scope of any legal rule or judicial holding. To build on the ideas above and do a little real legal analysis, let’s see an example of how generic context works in an example Holding based on United States v. Harmon, a recent case from the District Court of the District of Columbia.

First, we use AuthoritySpoke’s legislation download client to get the statute being interpreted. If you try out this code yourself, you’ll need to follow the directions for creating an environment variable called “LEGISLICE_API_TOKEN”.

>>> import os
>>> from dotenv import load_dotenv
>>> from authorityspoke.io.downloads import Client
>>> load_dotenv()
>>> LEGISLICE_API_TOKEN = os.getenv("LEGISLICE_API_TOKEN")
>>> CLIENT = Client(api_token=LEGISLICE_API_TOKEN)
>>> offense_statute = CLIENT.read("/us/usc/t18/s1960/a")
>>> print(offense_statute)
'"Whoever knowingly conducts, controls, manages, supervises, directs, or owns all or part of an unlicensed money transmitting business, shall be fined in accordance with this title or imprisoned not more than 5 years, or both." (/us/usc/t18/s1960/a 2013-07-18)'

Next, we create the Facts that the court found to be relevant to the elements of a criminal offense, and we combine them into a Holding.

>>> from authorityspoke import Entity, Fact, Holding, Predicate
>>> no_license = Fact(
...     "$business was licensed as a money transmitting business",
...     truth=False,
...     terms=Entity("Helix"))
>>> operated = Fact(
...     "$person operated $business as a business",
...     terms=[Entity("Harmon"), Entity("Helix")])
>>> transmitting = Fact(
...     "$business was a money transmitting business",
...     terms=Entity("Helix"))
>>> offense = Fact(
...     "$person committed the offense of conducting an unlicensed money transmitting business",
...     terms=Entity("Harmon"))
>>> offense_holding = Holding.from_factors(
...     inputs=[operated, transmitting, no_license],
...     outputs=offense,
...     enactments=offense_statute,
...     universal=True)

This Holding simply says that if a person has committed the elements of the offense, the court may convict the person of the offense.

>>> print(offense_holding)
"""the Holding to ACCEPT
  the Rule that the court MAY ALWAYS impose the
    RESULT:
      the fact that <Harmon> committed the offense of conducting an
      unlicensed money transmitting business
    GIVEN:
      the fact that <Harmon> operated <Helix> as a business
      the fact that <Helix> was a money transmitting business
      the fact it was false that <Helix> was licensed as a money
      transmitting business
    GIVEN the ENACTMENT:
      "Whoever knowingly conducts, controls, manages, supervises, directs, or owns all or part of an unlicensed money transmitting business, shall be fined in accordance with this title or imprisoned not more than 5 years, or both." (/us/usc/t18/s1960/a 2013-07-18)"""

And then we can create the more important Holding of the case, in which the court found that a bitcoin transmitting business met the statutory definition of a “money transmitting” business requiring a license.

>>> definition_statute = CLIENT.read("/us/usc/t18/s1960/b/2")
>>> bitcoin = Fact(
...     "$business transferred bitcoin on behalf of the public",
...     terms=Entity("Helix"))
>>> bitcoin_holding = Holding.from_factors(
...     inputs=bitcoin,
...     outputs=transmitting,
...     enactments=definition_statute,
...     universal=True)
>>> print(bitcoin_holding)
"""the Holding to ACCEPT
  the Rule that the court MAY ALWAYS impose the
    RESULT:
      the fact that <Helix> was a money transmitting business
    GIVEN:
      the fact that <Helix> transferred bitcoin on behalf of the public
    GIVEN the ENACTMENT:
      "the term “money transmitting” includes transferring funds on behalf of the public by any and all means including but not limited to transfers within this country or to locations abroad by wire, check, draft, facsimile, or courier; and" (/us/usc/t18/s1960/b/2 2013-07-18)"""

By adding the two Holdings above, we get a new Holding indicating that if a person operated a business that transferred bitcoin on behalf of the public without a “money transmitting business” license, the person may be found guilty of the offense. To generate this Holding, AuthoritySpoke finds that the terms named “Harmon” and “Helix” in offense_holding can be matched to the terms with the same names in bitcoin_holding.

>>> result = bitcoin_holding + offense_holding
>>> print(result)
"""the Holding to ACCEPT
  the Rule that the court MAY ALWAYS impose the
    RESULT:
      the fact that <Harmon> committed the offense of conducting an
      unlicensed money transmitting business
      the fact that <Helix> was a money transmitting business
    GIVEN:
      the fact that <Harmon> operated <Helix> as a business
      the fact it was false that <Helix> was licensed as a money
      transmitting business
      the fact that <Helix> transferred bitcoin on behalf of the public
    GIVEN the ENACTMENTS:
      "Whoever knowingly conducts, controls, manages, supervises, directs, or owns all or part of an unlicensed money transmitting business, shall be fined in accordance with this title or imprisoned not more than 5 years, or both." (/us/usc/t18/s1960/a 2013-07-18)
      "the term “money transmitting” includes transferring funds on behalf of the public by any and all means including but not limited to transfers within this country or to locations abroad by wire, check, draft, facsimile, or courier; and" (/us/usc/t18/s1960/b/2 2013-07-18)"""

Finally, once that Holding is created, we can also generalize the Holding by using a new context to apply it to different generic terms.

>>> result_with_new_context = result.new_context(
...     ([Entity("Harmon"), Entity("Helix")],
...    [Entity("Schrute"), Entity("Schrute Bucks")]))
>>> print(result_with_new_context)
"""the Holding to ACCEPT
  the Rule that the court MAY ALWAYS impose the
    RESULT:
      the fact that <Schrute> committed the offense of conducting an
      unlicensed money transmitting business
      the fact that <Schrute Bucks> was a money transmitting business
    GIVEN:
      the fact that <Schrute> operated <Schrute Bucks> as a business
      the fact it was false that <Schrute Bucks> was licensed as a money
      transmitting business
      the fact that <Schrute Bucks> transferred bitcoin on behalf of the
      public
    GIVEN the ENACTMENTS:
      "Whoever knowingly conducts, controls, manages, supervises, directs, or owns all or part of an unlicensed money transmitting business, shall be fined in accordance with this title or imprisoned not more than 5 years, or both." (/us/usc/t18/s1960/a 2013-07-18)
      "the term “money transmitting” includes transferring funds on behalf of the public by any and all means including but not limited to transfers within this country or to locations abroad by wire, check, draft, facsimile, or courier; and" (/us/usc/t18/s1960/b/2 2013-07-18)"""