PERRLA Reference Extractor

Overview

An early FastAPI reference-extraction prototype that accepts a Word-compatible OOXML package, inspects content controls in the main document XML, and applies narrow rule-based parsing to candidate citations. The prototype can return structured JSON or preliminary RIS text through a minimal browser interface. The implementation demonstrates a processing pipeline, but it does not yet establish PERRLA-specific compatibility, real-world extraction reliability, accuracy, or production readiness.

1. ✓DiscoveryComplete
2. 2ResearchNot complete
3. 3PlanningNot complete
4. ✓PrototypeComplete
5. 5ValidationNot complete
6. 6DocumentationNot complete
7. 7ReleaseNot complete
8. 8MaintenanceNot complete

Current Focus

The current engineering priority is turning the demonstration into a reproducible, testable baseline: define typed parsing outcomes, handle unknown citations explicitly, correct the MLA author-normalization mismatch, add safe document-processing limits, and introduce sanitized synthetic fixtures.

Design Decisions

Use FastAPI for the prototype boundary

Expose document submission and result selection through a small FastAPI service with a minimal browser client.

Inspect OOXML directly

Open the uploaded Word package in memory and read its main document XML instead of automating a desktop word processor.

Treat content controls as candidate record boundaries

Use WordprocessingML content controls to locate candidate reference text while recognizing that this does not yet prove PERRLA-specific structure.

Begin with rule-based citation parsing

Use narrow APA- and MLA-shaped regular-expression rules to demonstrate extraction before expanding the supported citation model.

Serve JSON and RIS from one extraction pass

Reuse the same parsed reference results for a JSON response and preliminary RIS serialization.

Tradeoffs

Direct OOXML inspection instead of desktop automation

Direct parsing keeps the prototype small and cross-platform, but requires the application to interpret document structure and text boundaries itself.

Content controls as extraction boundaries

Content controls offer a simple way to locate structured regions, but unrelated controls can be mistaken for references and references outside them remain invisible.

Regular expressions instead of a broader citation parser

The rules are transparent and dependency-light, but support only a narrow range of names, punctuation, source types, and citation variations.

In-memory, request-scoped processing

The prototype avoids a persistence layer and filesystem extraction, but it still needs explicit resource limits before handling untrusted or large documents.

One compact backend module

A single module makes the experiment easy to inspect, while coupling transport, parsing, serialization, and startup behavior in ways that make focused testing harder.

Known Limitations

• The implementation does not identify PERRLA-specific metadata or establish compatibility with PERRLA-generated documents.
• No tracked real-world document fixtures or extraction-result corpus establish accuracy or reliable document coverage.
• The MLA author matcher and author-normalization rule use incompatible name orders, causing matched author values to be discarded.
• The RIS serializer emits fields that the current parser does not populate, and source types are assigned by broad citation-style assumptions.
• Unknown citation styles do not produce a stable explicit result, which can create incomplete JSON entries or interrupt RIS generation.
• Application-level limits for uploaded archives, expanded document data, and XML processing are not yet implemented.
• There is no tracked automated test suite or representative OOXML fixture set.
• Dependencies, supported Python versions, and repeatable build or packaging steps are not declared in tracked project configuration.
• The prototype has not established production deployment, operational privacy controls, or production readiness.

Development Log

Lessons Learned

• A structured document container does not establish the meaning of its contents; content controls still need source-specific identification before they can be treated as references.
• Citation detection and normalization rules need a shared contract so one stage does not discard values accepted by another.
• An interchange serializer cannot recover bibliographic fields that the extraction model never captured.
• Unknown and partially parsed citations need explicit result states instead of implicit empty values.
• Browser file restrictions are usability guidance, not a substitute for server-side document validation and resource limits.

Future Improvements

• Add reproducible Python project metadata with declared and pinned runtime dependencies.
• Introduce typed reference, partial-result, and error models shared by JSON and RIS output.
• Move synthetic parsing examples into assertion-based automated tests.
• Build sanitized synthetic OOXML fixtures for supported, unsupported, and malformed document structures.
• Correct MLA author normalization and add Unicode-aware name handling.
• Validate archive structure, output format, and document-processing limits before parsing.
• Establish the PERRLA-specific document structure using authorized, sanitized evidence before claiming compatibility.
• Expand RIS mapping only for fields and source types supported by tested extraction evidence.
• Define privacy, access, logging, and retention requirements before any shared deployment.

Future Direction

Future work should validate the actual PERRLA-produced document structure with authorized, sanitized evidence before adding source-specific extraction rules. Broader citation coverage, more complete RIS mapping, operational privacy controls, and any deployment architecture should follow only after the input contract and automated validation are established.