Skip to content

CLAUDE.md

Latest commit

 

History

History
108 lines (80 loc) · 3.78 KB

CLAUDE.md

File metadata and controls

108 lines (80 loc) · 3.78 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a fork of the freelawproject's eyecite that is being oxidized (ported from Python to Rust). Eyecite is a tool for extracting legal citations from text, recognizing various citation formats including full case citations, statutory citations, law journal citations, and reference citations (supra, id., etc.).

Architecture

Python → Rust Port Mapping

The Rust port maintains a similar structure to the Python codebase with the following key mappings:

Core Modules:

  • eyecite/__init__.py → src/lib.rs - Main library entry point
  • eyecite/find.py → src/find.rs - Citation extraction logic
  • eyecite/models.py → src/find/models.rs - Citation data structures
  • eyecite/tokenizers.py → src/tokenizers.rs - Text tokenization
  • eyecite/regexes.py → src/regexes.rs - Regular expressions for pattern matching

Key Components:

  1. Tokenizers: Convert text into tokens (citations, stop words, sections, etc.)

    • Python: Uses pyahocorasick for efficient string matching
    • Rust: Uses daachorse (Double Array Aho-Corasick) for the same purpose

  2. Citation Models:

    • Python: Dataclasses with inheritance hierarchy (CitationBase → FullCaseCitation, etc.)
    • Rust: Enum-based approach with Citation enum containing variants for each citation type

  3. Token Types:

    • Python: Class hierarchy with Token base class
    • Rust: Token enum with variants (Word, Space, Citation, Section, Supra, Id, etc.)

Development Commands

Python (Original)

# Run tests
uv run python -m unittest discover -s tests -p 'test_*.py'

# Install dependencies
pip install eyecite

Rust (Port)

# Build
cargo build

# Run tests
cargo test

# Run clippy
cargo clippy

# Format code
cargo fmt

# Run with cargo-husky hooks (configured in Cargo.toml)
cargo test  # Will trigger pre-commit/pre-push hooks

Key Implementation Details

Tokenization Process

  1. Text is processed through extractors that identify patterns (citations, stop words, etc.)
  2. Aho-Corasick algorithm efficiently finds all pattern matches
  3. Tokens are created with position information and metadata
  4. Overlapping tokens are merged when possible

Citation Types Supported

  • FullCase: Complete case citations with names and reporters
  • ShortCase: Abbreviated references to previously cited cases
  • Law: Statutory citations (e.g., "Mass. Gen. Laws ch. 1, § 2")
  • Journal: Law review and journal citations
  • Supra: References to citations above in the document
  • Id: References to immediately preceding citations
  • Unknown: Catch-all for unrecognized citation patterns

Key Dependencies

  • reporters-db: Database of legal reporters (local path: ../reporters-db)
  • regex: Regular expression processing
  • daachorse: Efficient string matching (Rust port of pyahocorasick)

Current State of Port

The Rust implementation currently has:

  • Basic tokenizer infrastructure (Ahocorasick tokenizer)
  • Token models and citation models defined
  • Regex patterns ported from Python
  • Test infrastructure started

Still needs implementation:

  • Complete get_citations() function logic
  • Citation extraction functions (_extract_full_citation, _extract_shortform_citation, etc.)
  • Helper functions for disambiguation and filtering
  • Annotation and resolution functionality
  • Clean text functionality

Testing

The Python test suite in tests/ directory provides comprehensive test cases that should be ported to Rust tests. Key test files:

  • test_FindTest.py - Citation extraction tests
  • test_TokenizeTest.py - Tokenization tests
  • test_RegexTest.py - Regex pattern tests
  • test_ResolveTest.py - Citation resolution tests