Upload 2 files

README.md

@@ -1,14 +1,406 @@
+### Lexie – Legal Compliance Assistant (base)
+
+
+
+**Setup**
+
+-----
+
+pip install -r requirements.txt
+
+\# for analysis:
+
+pip install openai
+
+\# Windows PowerShell:
+
+setx OPENAI\_API\_KEY "sk-..."
+
+
+
+Commands
+
+--------
+
+python main.py build-index
+
+python main.py test-retriever
+
+python main.py analyze-demo
+
+
+
+
+
+
+
+**🧠 Design Principles**
+
+
+
+**Lexie** was built with a modular and agentic mindset, inspired by emerging best practices in AI-assisted development. Rather than relying on monolithic prompting or magic workflows, Lexie applies strategic separation of concerns and methodical orchestration. Key principles include:
+
+
+
+* Context-First Setup: Each task is approached like briefing a junior developer — with clear structure, expected behavior, and explicit constraints before any generation occurs.
+
+
+
+* Test-by-Design: The logic of Lexie is enforced by validations and controlled outputs (e.g., maximum number of citations, placeholder filtering), reducing ambiguity and maximizing reliability.
+
+
+
+* Rule-Based Core: A centralized configuration (config.py) and logic definitions (postprocess.py) act as an internal operating system, guiding how the system behaves and responds.
+
+
+
+* Unified Workspace: All modules operate within a coherent and tightly scoped folder structure (lexie/), ensuring clarity, traceability, and easy collaboration.
+
+
+
+* Model Mixing Strategy: Lexie combines small open-source models (e.g. for chunking and embedding with MiniLM) with powerful LLMs (GPT-4) for legal reasoning and summarization. This approach balances speed, cost, and analytical depth.
+
+
+
+* Iterative, Human-in-the-Loop Development: Every feature is tested incrementally, reviewed critically, and refined through live interactions and error tracing.
+
+
+
+Lexie is not a “prompt wrapper” — it’s a real-world application of AI as a reasoning assistant. The focus is on clarity, control, and meaningful outputs.
+
+
+
 ---
-title: Lexie
-emoji: 🏃
-colorFrom: purple
-colorTo: purple
-sdk: gradio
-sdk_version: 5.44.1
-app_file: app.py
-pinned: false
-license: mit
-short_description: Agentic AI to verify compliance with GDPR and AI Act.
+
+
+
+**🤝 Collaborative AI Development**
+
+
+
+Lexie was developed in close collaboration with ChatGPT (GPT-4 and 5), used not merely as a coding assistant but as a reasoning partner throughout the project lifecycle. From architectural decisions to prompt engineering, from debugging complex errors to refining user-facing outputs, ChatGPT served as a real-time co-designer,  especially valuable during early-stage prototyping and iterative testing.
+
+
+
+The collaboration was guided by clear instructions, step-by-step validation, and a critical mindset: ChatGPT’s outputs were always reviewed, edited, and validated by a human before being integrated into the codebase.
+
+
+
+This project stands as an example of human-in-the-loop agentic development, where AI tools are treated as powerful collaborators,  not autopilots. The result is a system that reflects both technical coherence and creative decision-making.
+
+
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+
+🧪 **Testing in Lexie**
+
+
+
+Lexie includes a dedicated tests/ folder to ensure stability and prevent regressions as the project evolves. The goal is not bureaucracy, but trust and speed:
+
+
+
+* Regression safety: whenever you update a file, you can run pytest and immediately see if something broke.
+
+
+
+* Architecture clarity: all test cases are kept separate from the main code, but close enough for quick checks.
+
+
+
+* Professional credibility: showing a reproducible test suite proves Lexie is a serious, production-ready tool.
+
+
+
+**📂 Test structure**
+
+
+
+lexie/
+
+  main.py
+
+  call\_agent.py
+
+  pdf\_reporter.py
+
+  tools/
+
+  requirements.txt
+
+  requirements-dev.txt  
+
+  tests/
+
+    fixtures/
+
+      iubenda.pdf
+
+&nbsp;     iubenda\_snapshot.normalized.txt   <-- golden reference
+
+&nbsp;     info\_breve.pdf
+
+&nbsp;     dpa\_bozza.pdf
+
+&nbsp;   helpers/
+
+&nbsp;     pdf\_extract.py
+
+&nbsp;     run\_cli.py
+
+&nbsp;   test\_pdf\_snapshot.py
+
+&nbsp;   test\_postprocess\_rules.py
+
+&nbsp;   test\_free\_text\_smoke.py
+
+&nbsp;   conftest.py
+
+
+
+
+
+* tests/fixtures/ → input documents and golden snapshots.
+* tests/helpers/ → utilities to extract and normalize PDF text, and to run the CLI.
+* tests/test\_pdf\_snapshot.py → snapshot test for iubenda.pdf and smoke test for short documents.
+* tests/test\_free\_text\_smoke.py → smoke test for free-text input.
+* tests/test\_postprocess\_rules.py → unit tests for post-process rules.
+
+
+
+**🔎 Types of tests**
+
+
+
+1. **Snapshot test (golden)**
+
+
+
+* Compares the PDF generated from iubenda.pdf with the reference file iubenda\_snapshot.normalized.txt.
+
+
+
+* Purpose: catch invisible regressions in layout or content.
+
+
+
+* Rule: if the diff is a bug �� fix the code; if it’s an intended change → update the golden file.
+
+
+
+**2. Smoke tests**
+
+
+
+* Run on a short document (info\_breve.pdf) and on free-text input.
+
+
+
+* Check that the generated PDF always includes:
+
+
+
+&nbsp;	- risk/score header
+
+
+
+&nbsp;	- key sections: Violations, Recommendations, Citations
+
+
+
+**3. Unit tests (post-process)**
+
+
+
+* Verify that the normalization and consistency rules are respected:
+
+
+
+&nbsp;	- Multi-hit on the same article is allowed.
+
+
+
+&nbsp;	- Title/article mismatch generates a warning, not an error.
+
+
+
+&nbsp;	- Citation cap is enforced if configured.
+
+
+
+**📌 Golden file explained**
+
+
+
+A golden file is a frozen output used as reference.
+
+For Lexie, the golden is iubenda\_snapshot.normalized.txt.
+
+
+
+How it works:
+
+
+
+* First run: Lexie processes iubenda.pdf, the normalized text is saved as golden.
+
+
+
+* Future runs: the test compares the new output against the golden.
+
+
+
+* If they match → stable.
+
+
+
+* If they differ:
+
+
+
+&nbsp;	- Bug → fix the pipeline.
+
+
+
+&nbsp;	- Intended change → overwrite the golden with the new output.
+
+
+
+This acts as a **photograph** of the expected behavior.
+
+
+
+**⚡ How to run tests**
+
+
+
+Install dependencies:
+
+
+
+pip install -r requirements.txt       # runtime
+
+pip install -r requirements-dev.txt   # dev \& test
+
+
+
+
+
+Run the full suite:
+
+
+
+pytest tests/ -q
+
+
+
+
+
+Run a single test:
+
+
+
+pytest tests/test\_pdf\_snapshot.py::test\_iubenda\_snapshot -q
+
+
+
+
+
+&nbsp;                  ┌──────────────────────────────────────────┐
+
+&nbsp;                  │            LEXIE PIPELINE                │
+
+&nbsp;                  │ route → retrieve → analyze → postprocess │
+
+&nbsp;                  │                 → pdf\_reporter           │
+
+&nbsp;                  └───────────────┬───────────────┬─────────┘
+
+&nbsp;                                  │               │
+
+&nbsp;                            (document)        (free-text)
+
+&nbsp;                                  │               │
+
+&nbsp;                            input .pdf        input string
+
+&nbsp;                                  │               │
+
+&nbsp;                                  ▼               ▼
+
+&nbsp;                          ┌─────────────────────────────┐
+
+&nbsp;                          │   NORMALIZED PDF TEXT       │
+
+&nbsp;                          └─────────────────────────────┘
+
+
+
+
+
+**Test Levels**
+
+
+
+\[1] SNAPSHOT (GOLDEN) ──────────────────────────────────────────────────────────
+
+&nbsp;   Input: tests/fixtures/iubenda.pdf
+
+&nbsp;   Check: compare normalized PDF text ⇆ iubenda\_snapshot.normalized.txt
+
+&nbsp;   Outcome:
+
+&nbsp;     = pass → behavior stable
+
+&nbsp;     ≠ diff → bug OR intended change → update golden
+
+
+
+\[2] SMOKE (DOCUMENT) ───────────────────────────────────────────────────────────
+
+&nbsp;   Input: tests/fixtures/info\_breve.pdf
+
+&nbsp;   Check: "risk:" + "score:" + sections {violations, recommendations, citations}
+
+
+
+\[3] SMOKE (FREE-TEXT) ──────────────────────────────────────────────────────────
+
+&nbsp;   Input: "We collect facial images without consent."
+
+&nbsp;   Check: same header + same sections as document smoke
+
+
+
+\[4] UNIT (POST-PROCESS) ────────────────────────────────────────────────────────
+
+&nbsp;   Target: tools/postprocess.enforce\_rules(...)
+
+&nbsp;   Checks:
+
+&nbsp;     - multi-hit same article = allowed
+
+&nbsp;     - title/article mismatch → WARNING (non-blocking)
+
+&nbsp;     - citations cap respected (if configured)
+
+
+
+**Golden Update Flow**
+
+
+
+Run snapshot → diff?
+
+&nbsp;  ├─ No → done
+
+&nbsp;  └─ Yes
+
+&nbsp;      ├─ Bug → fix code → rerun
+
+&nbsp;      └─ Intended change → overwrite iubenda\_snapshot.normalized.txt → rerun
+
+
+

requirements.txt

@@ -0,0 +1,6 @@
+gradio>=4.44
+reportlab>=4.1
+pdfminer.six>=20231228
+PyYAML>=6.0.1
+openai>=1.40
+numpy>=1.26