Package: blackstone
BlackstoneBlackstone is aspaCymodel and library for processing long-form, unstructured legal text. Blackstone is an experimental research project from theIncorporated Council of Law Reporting for England and Wales'research lab,ICLR&D.ContentsWhy are we building Blackstone?What's special about Blackstone?Observations and other things worth notingInstallationInstall the libraryInstall the Blackstone modelAbout the modelThe pipelineNamed-Entity RecogniserText categoriserUsageApplying the NER modelVisualising entitiesApplying the text categoriser modelCustom pipeline extensionsAbbreviation and long-form definition resolutionCompound case reference detectionsLegislation linkerSentence segmenterWhy are we building Blackstone?The past several years have seen a surge in activity at the intersection of law and technology. However, in the United Kingdom, the overwhelming bulk of that activity has taken place in law firms and other commercial contexts. The consequence of this is that notwithstanding the never ending flurry of development in the legal-informatics space, almost none of the research is made available on an open-source basis.Moreover, the majoritry of research in the UK legal-informatics domain (whether open or closed) has focussed on the development of NLP applications for automating contracts and other legal documents that are transactional in nature. This is understandable, because the principal benefactors of legal NLP research in the UK are law firms and law firms tend not to find it difficult to get their hands on transactional documentation that can be harnessed as training data.The problem, as we see it, is that legal NLP research in the UK has become over concentrated on commercial applications and that it is worthwhile making the investment in developing legal NLP research available with respect to other legal texts, such as judgments, scholarly articles, skeleton arguments and pleadings.What's special about Blackstone?So far as we are aware, Blackstone is the first open source model trained for use on long-form texts containing common law entities and concepts.Blackstone is built onspaCy, which makes it easy to pick up and apply to your own data.Blackstone has been trained on data spanning a considerable temporal period (as early as texts drafted in the 1860s). This is useful because an interesting quirk of the common law is that older writings (particularly, judgments) go on to remain relevant for many, many years.It is free and open sourceIt is imperfect and makes no attempt to hide that fact from youObservations and other things worth noting:Perfection is the enemy of the good. This is a prototype release of highly experimental project. As such, the accuracy of Blackstone's models leaves something to be desired (F1 on the NER is approx 70%). The accuracy of these models will improve over time.The models have been trained on English case law and the library has been built with the peculiarities of the legal system of England and Wales in mind. That said, the model has generalised well and should do a reasonably good job on Australasian, Canadian and American content, too.The data used to train Blackstone's models was derived from theIncorporated Council of Law Reporting for England and Wales'archive of case reports and unreported judgments. That archive is proprietary and this prevents us from releasing any of the data used to train Blackstone.Blackstone is not a judge or litigation analytics tool.InstallationNote!It is strongly recommended that you install Blackstone into a virtual environment! Seeherefor more on virtual environments. Blackstone should compatible with Python 3.6 and higher.To install Blackstone follow these steps:1. Install the libraryThe first step is to install the library, which at present contains a handful of customspaCycomponents. Install the library like so:pip install blackstone2. Install the Blackstone modelThe second step is to install thespaCymodel. Install the model like so:pip install https://blackstone-model.s3-eu-west-1.amazonaws.com/en_blackstone_proto-0.0.2.tar.gzAbout the modelThis is the very first release of Blackstone and the model is best viewed as aprototype; it is rough around the edges and represents the first step in a larger ongoing programme of open source research into NLP on legal texts being carried out by ICLR&D.With that out of the way, here's a brief rundown of what's happening in the proto model.The pipelineThe proto model included in this release has the following elements in its pipeline:Owing to a scarcity of labelled part-of-speech and dependency training data for legal text, thetokenizer,taggerandparserpipeline components have been taken fromspaCy'sen_core_web_smmodel. By and large, these components appear to a do a decent job, but it would be good to revisit these components with custom training data at some point in the future.Thenerandtextcatcomponents are custom components trained especially for Blackstone.Named-Entity RecogniserThe NER component of the Blackstone model has been trained to detect the following entity types:EntNameExamplesCASENAMECase namese.g.Smith v Jones,In re Jones, InJones'caseCITATIONCitations (unique identifiers for reported and unreported cases)e.g. (2002) 2 Cr App R 123INSTRUMENTWritten legal instrumentse.g. Theft Act 1968, European Convention on Human Rights, CPRPROVISIONUnit within a written legal instrumente.g. section 1, art 2(3)COURTCourt or tribunale.g. Court of Appeal, Upper TribunalJUDGEReferences to judgese.g. Eady J, Lord Bingham of CornhillText CategoriserThis release of Blackstone also comes with a text categoriser. In contrast with the NER component (which has been trainined to identify tokens and series of tokens of interest), the text categoriser classifies longer spans of text, such as sentences.The Text Categoriser has been trained to classify text according to one of five mutually exclusive categories, which are as follows:CatDescriptionAXIOMThe text appears to postulate a well-established principleCONCLUSIONThe text appears to make a finding, holding, determination or conclusionISSUEThe text appears to discuss an issue or questionLEGAL_TESTThe test appears to discuss a legal testUNCATThe text does not fall into one of the four categories aboveUsageApplying the NER modelHere's an example of how the model is applied to some text taken from para 31 of the Divisional Court's judgment inR (Miller) v Secretary of State for Exiting the European Union (Birnie intervening)[2017] UKSC 5; [2018] AC 61:importspacy# Load the modelnlp=spacy.load("en_blackstone_proto")text=""" 31 As we shall explain in more detail in examining the submission of the Secretary of State (see paras 77 and following), it is the Secretary of State’s case that nothing has been done by Parliament in the European Communities Act 1972 or any other statute to remove the prerogative power of the Crown, in the conduct of the international relations of the UK, to take steps to remove the UK from the EU by giving notice under article 50EU for the UK to withdraw from the EU Treaty and other relevant EU Treaties. The Secretary of State relies in particular on Attorney General v De Keyser’s Royal Hotel Ltd [1920] AC 508 and R v Secretary of State for Foreign and Commonwealth Affairs, Ex p Rees-Mogg [1994] QB 552; he contends that the Crown’s prerogative power to cause the UK to withdraw from the EU by giving notice under article 50EU could only have been removed by primary legislation using express words to that effect, alternatively by legislation which has that effect by necessary implication. The Secretary of State contends that neither the ECA 1972 nor any of the other Acts of Parliament referred to have abrogated this aspect of the Crown’s prerogative, either by express words or by necessary implication."""# Apply the model to the textdoc=nlp(text)# Iterate through the entities identified by the modelforentindoc.ents:print(ent.text,ent.label_)>>>EuropeanCommunitiesAct1972INSTRUMENT>>>article50EUPROVISION>>>EUTreatyINSTRUMENT>>>AttorneyGeneralvDeKeyser’sRoyalHotelLtdCASENAME>>>[1920]AC508CITATION>>>RvSecretaryofStateforForeignandCommonwealthAffairs,ExpRees-MoggCASENAME>>>[1994]QB552CITATION>>>article50EUPROVISIONVisualising entitiesspaCyships with an excellentset of visualisers, including a visualiser for NER predicts. Blackstone comes with a custom colour palette that can be used to make it easier to distiguish entities on the source text when using displacy."""Visualise entities using spaCy's displacy visualiser.Blackstone has a custom colour palette: `from blackstone.displacy_palette import ner_displacy options`"""importspacyfromspacyimportdisplacyfromblackstone.displacy_paletteimportner_displacy_optionsnlp=spacy.load("en_blackstone_proto")text="""The applicant must satisfy a high standard. This is a case where the action is to be tried by a judge with a jury. The standard is set out in Jameel v Wall Street Journal Europe Sprl [2004] EMLR 89, para 14:“But every time a meaning is shut out (including any holding that the words complained of either are, or are not, capable of bearing a defamatory meaning) it must be remembered that the judge is taking it upon himself to rule in effect that any jury would be perverse to take a different view on the question. It is a high threshold of exclusion. Ever since Fox’s Act 1792 (32 Geo 3, c 60) the meaning of words in civil as well as criminal libel proceedings has been constitutionally a matter for the jury. The judge’s function is no more and no less than to pre-empt perversity. That being clearly the position with regard to whether or not words are capable of being understood as defamatory or, as the case may be, non-defamatory, I see no basis on which it could sensibly be otherwise with regard to differing levels of defamatory meaning. Often the question whether words are defamatory at all and, if so, what level of defamatory meaning they bear will overlap.”18 In Berezovsky v Forbes Inc [2001] EMLR 1030, para 16 Sedley LJ had stated the test this way:“The real question in the present case is how the courts ought to go about ascertaining the range of legitimate meanings. Eady J regarded it as a matter of impression. That is all right, it seems to us, provided that the impression is not of what the words mean but of what a jury could sensibly think they meant. Such an exercise is an exercise in generosity, not in parsimony.”"""doc=nlp(text)# Call displacy and pass `ner_displacy_options` into the option parameter`displacy.serve(doc,style="ent",options=ner_displacy_options)Which produces something that looks like this:Applying the text categoriser modelBlackstone's text categoriser generates a predicted categorisation for adoc. Thetextcatpipeline component has been designed to be applied to individual sentences rather than a single document consisting of many sentences.importspacy# Load the modelnlp=spacy.load("en_blackstone_proto")defget_top_cat(doc):"""Function to identify the highest scoring categoryprediction generated by the text categoriser."""cats=doc.catsmax_score=max(cats.values())max_cats=[kfork,vincats.items()ifv==max_score]max_cat=max_cats[0]return(max_cat,max_score)text="""It is a well-established principle of law that the transactions of independent states between each other are governed by other laws than those which municipal courts administer.\It is, however, in my judgment, insufficient to react to the danger of over-formalisation and “judicialisation” simply by emphasising flexibility and context-sensitivity.\The question is whether on the facts found by the judge, the (or a) proximate cause of the loss of the rig was “inherent vice or nature of the subject matter insured” within the meaning of clause 4.4 of the Institute Cargo Clauses (A)."""# Apply the model to the textdoc=nlp(text)# Get the sentences in the passage of textsentences=[sent.textforsentindoc.sents]# Print the sentence and the corresponding predicted category.forsentenceinsentences:doc=nlp(sentence)top_category=get_top_cat(doc)print(f"\"{sentence}\"{top_category}\n")>>>"In my judgment, it is patently obvious that cats are a type of dog."('CONCLUSION',0.9990500807762146)>>>"It is a well settled principle that theft is wrong."('AXIOM',0.556410014629364)>>>"The question is whether on the facts found by the judge, the (or a) proximate cause of the loss of the rig was “inherent vice or nature of the subject matter insured” within the meaning of clause 4.4 of the Institute Cargo Clauses (A)."('ISSUE',0.5040785074234009)Custom pipeline extensionsIn addition to the core model, this proto release of Blackstone comes with three custom components:Abbreviation detection - this isheavilybased on theAbbreviationDetector()component in [scispacy] and resolves an abbreviated form to its long form definition, e.g.ECtHR->European Court of Human Rights.Legislation linker - this is an alpha component that attempts to resolve references to provisons to their parent instrument (more on this further down the README).Compound case reference detection - again, this is an alpha component that attempts identifyCASENAMEandCITATIONpairs enabling the merging of aCITATIONto its parentCASENAME.Abbreviation detection and long-form definition resolutionIt is not uncommon for authors of legal documents to abbreviate long-winded terms that will be used instead of the long-form througout the rest of the document. For example,The European Court of Human Rights ("ECtHR") is the court ultimately responsible for applying the European Convention on Human Rights ("ECHR").The abbreviation detection component in Blackstone seeks to address this by implementing an ever so slightly modified version ofscispaCy'sAbbreviationDetector()(which is itself an implementation of the approach set out in this paper:https://psb.stanford.edu/psb-online/proceedings/psb03/schwartz.pdf). Our implementation still has some problems, but an example of its usage is as follows:importspacyfromblackstone.pipeline.abbreviationsimportAbbreviationDetectornlp=spacy.load("en_blackstone_proto")# Add the abbreviation pipe to the spacy pipeline.abbreviation_pipe=AbbreviationDetector(nlp)nlp.add_pipe(abbreviation_pipe)doc=nlp('The European Court of Human Rights ("ECtHR") is the court ultimately responsible for applying the European Convention on Human Rights ("ECHR").')print("Abbreviation","\t","Definition")forabrvindoc._.abbreviations:print(f"{abrv}\t({abrv.start},{abrv.end}){abrv._.long_form}")>>>"ECtHR"(7,10)EuropeanCourtofHumanRights>>>"ECHR"(25,28)EuropeanConventiononHumanRightsCompound case reference detectionThe compound case reference detection component in Blackstone is designed to marry upCITATIONentities with their parentCASENAMEentities.Common law jurisdictions typically relate to case references through a coupling of a name (typically derived from the names of the parties in the case) and some unique citation to identify where the case has been reported, like so:Regina v Horncastle [2010] 2 AC 373Blackstone's NER model separately attempts to identify theCASENAMEandCITATIONentities. However, it is potentially useful (particularly in the context of information extraction) to pull these entities out as pairs.CompoundCases()applies a custom pipe after the NER and identifiesCASENAME/CITATIONpairs in two scenarios:The standard scenario: Gelmini v Moriggia [1913] 2 KB 549The possessive scenario (which is a little antiquated): Jone's case [1915] 1 KB 45importspacyfromblackstone.pipeline.compound_casesimportCompoundCasesnlp=spacy.load("en_blackstone_proto")compound_pipe=CompoundCases(nlp)nlp.add_pipe(compound_pipe)text="As I have indicated, this was the central issue before the judge. On this issue the defendants relied (successfully below) on the decision of the High Court in Gelmini v Moriggia [1913] 2 KB 549. In Jone's case [1915] 1 KB 45, the defendant wore a hat."doc=nlp(text)forcompound_refindoc._.compound_cases:print(compound_ref)>>>GelminivMoriggia[1913]2KB549>>>Jone's case [1915] 1 KB 45Legislation linkerBlackstone's Legislation Linker attempts to couple a reference to aPROVISIONto it's parentINSTRUMENTby using the NER model to identify the presence of anINSTRUMENTand then navigating the dependency tree to identify the child provision.Once Blackstone has identified aPROVISION:INSTRUMENTpair, it will attempt to generate target URLs to both the provision and the instrument onlegislation.gov.uk.importspacyfromblackstone.utils.legislation_linkerimportextract_legislation_relationsnlp=spacy.load("en_blackstone_proto")text="The Secretary of State was at pains to emphasise that, if a withdrawal agreement is made, it is very likely to be a treaty requiring ratification and as such would have to be submitted for review by Parliament, acting separately, under the negative resolution procedure set out in section 20 of the Constitutional Reform and Governance Act 2010. Theft is defined in section 1 of the Theft Act 1968"doc=nlp(text)relations=extract_legislation_relations(doc)forprovision,provision_url,instrument,instrument_urlinrelations:print(f"\n{provision}\t{provision_url}\t{instrument}\t{instrument_url}")>>>section20http://www.legislation.gov.uk/ukpga/2010/25/section/20ConstitutionalReformandGovernanceAct2010http://www.legislation.gov.uk/ukpga/2010/25/contents>>>section1http://www.legislation.gov.uk/ukpga/1968/60/section/1TheftAct1968http://www.legislation.gov.uk/ukpga/1968/60/contentsSentence segmenterBlackstone ships with a custom rule-based sentence segmenter that addresses a range of characteristics inherent in legal texts that have a tendency to baffle out-of-the-box sentence segmentation rules.This behaviour can be extended by optionally passing a list of spaCy-style Matcher patterns that will explicitly prevent sentence boundary detection inside matches.importspacyfromblackstone.pipeline.sentence_segmenterimportSentenceSegmenterfromblackstone.rulesimportCITATION_PATTERNSnlp=spacy.load("en_blackstone_proto")# add the Blackstone sentence_segmenter to the pipeline before the parsersentence_segmenter=SentenceSegmenter(nlp.vocab,CITATION_PATTERNS)nlp.add_pipe(sentence_segmenter,before="parser")doc=nlp("""The courts in this jurisdiction will enforce those commitments when it is legally possible and necessary to do so (see, most recently, R. (on the application of ClientEarth) v Secretary of State for the Environment, Food and Rural Affairs (No.2) [2017] P.T.S.R. 203 and R. (on the application of ClientEarth) v Secretary of State for Environment, Food and Rural Affairs (No.3) [2018] Env. L.R. 21). The central question in this case arises against that background.""")forsentindoc.sents:print(sent.text)ThanksWe would like to thank the following people/organisations who have helped us (directly or indirectly) to build this prototype.Mark NeumannofAI2andscispaCyExplosion AIfor buildingspaCyandProdigyKristin Hodginsof the Office of the Attorney General of British Columbia