astraea-framework 0.1.0__py3-none-any.whl

astraea_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: astraea-framework
+Version: 0.1.0
+Summary: Open-justice RAG framework - jurisdiction-specific legal Q&A over public court decisions
+Author-email: jsaputra@riseup.net
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jwongso/astraea
+Project-URL: Issues, https://github.com/jwongso/astraea/issues
+Keywords: legal,rag,llm,tenancy,jurisdiction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: qdrant-client>=1.9
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: redis>=5.0
+Requires-Dist: cachetools>=5.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: ingest
+Requires-Dist: beautifulsoup4>=4.12; extra == "ingest"
+Requires-Dist: pypdf>=4.0; extra == "ingest"
+Requires-Dist: pytesseract>=0.3; extra == "ingest"
+Requires-Dist: pillow>=10.0; extra == "ingest"
+Dynamic: license-file
+
+# Astraea
+
+Open-justice RAG framework for building jurisdiction-specific legal Q&A tools over public court decisions.
+
+Named after Astraea, the Greek goddess of justice who carried the scales.
+
+---
+
+## What it is
+
+A small runtime framework that provides the infrastructure for legal RAG tools - SSE streaming,
+concurrent request queue, statute routing, live legislation anchors, citation verification,
+security hardening, and smoke tests - so that a new jurisdiction only needs to provide one Python module.
+
+```python
+from jurisdictions.nz_tenancy import jurisdiction
+from core.api import create_app
+
+app = create_app(jurisdiction)
+```
+
+---
+
+## Design principles
+
+- **One process = one jurisdiction.** No multi-tenancy, no plugin registry. Simple deployment.
+- **Four required things.** A jurisdiction must provide: a name, a corpus config, a system prompt, and a route table. Everything else has a working default.
+- **Security and queue are non-overridable.** Input sanitization, request body limits, security headers, and queue concurrency are enforced by core regardless of jurisdiction config.
+- **Scraper is offline.** Ingestion runs separately from the API. Core only needs a populated Qdrant collection conforming to `schemas/qdrant_payload.schema.json`.
+- **Tests are data-driven.** Jurisdictions provide smoke test fixtures; core runs the test suite against them automatically.
+
+---
+
+## Supported jurisdictions
+
+| Jurisdiction | Status | Corpus |
+|---|---|---|
+| NZ Tenancy (`nz_tenancy`) | Live - tenancy.localrun.ai | 31,000+ Tenancy Tribunal decisions, RTA 1986 + Healthy Homes Standards 2019 |
+| NZ Legal (`nz_legal`) | Live - nz-legal-rag.localrun.ai | All NZ courts, 3M+ chunks (NZHC, NZCA, NZSC, NZERA, NZEmpC, NZTT) |
+| NZ Employment (`nz_employment`) | Ready | 300+ ERA + Employment Court decisions through May 2026, live ERA 2000 |
+| NSW Tenancy (`nsw_tenancy`) | PoC (framework demo) | Proves interface generalises - not actively developed |
+
+---
+
+## Adding a new jurisdiction
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full fork-to-running walkthrough.
+
+Quick version:
+
+1. Copy `examples/minimal_jurisdiction/` to `jurisdictions/your_name/`
+2. Implement the 4 required properties in `jurisdiction.py`
+3. Run the contract tests: `pytest tests/core/test_jurisdiction_contract.py --jurisdiction your_name`
+4. Ingest your corpus into Qdrant (see `ingest/` and `schemas/qdrant_payload.schema.json`)
+5. Add smoke fixtures and run: `pytest tests/jurisdictions/test_smoke.py --jurisdiction your_name -m retrieval`
+
+---
+
+## Jurisdiction extension points
+
+Beyond the 4 required properties, jurisdictions can opt into additional behaviour:
+
+### Extra routes (`register_routes`)
+
+Add jurisdiction-specific endpoints (e.g. structured data trackers) on top of the core API:
+
+```python
+def register_routes(self, app: FastAPI) -> None:
+    from jurisdictions.nz_legal.routes import register
+    register(app)
+```
+
+Called at the end of `create_app()`. Route handlers access pipeline and store via `request.app.state`.
+
+`nz_legal` uses this to expose `/search`, `/notable`, `/sentencing-tracker`, `/pg-tracker`, and `/contrasting-cases`.
+
+### Federated per-Act legislation retrieval (`leg_sources`)
+
+By default, legislation retrieval does one vector search across the entire legislation collection.
+As a corpus grows (more Acts), smaller Acts get crowded out by larger ones on embedding similarity alone.
+
+Override `leg_sources` to run one search per registered Act in parallel, each with its own `top_k` quota.
+The re-ranker phase (Phase 2) can then select the best sections across all sources without manual routes:
+
+```python
+from core.jurisdiction import LegislationSource
+
+@property
+def leg_sources(self) -> list[LegislationSource]:
+    return [
+        LegislationSource("RTA",    "Residential Tenancies Act 1986",                         default_top_k=6, boost_top_k=10),
+        LegislationSource("HHS2019","Residential Tenancies (Healthy Homes Standards) Regulations 2019", default_top_k=4, boost_top_k=8),
+    ]
+```
+
+When a matched route targets a specific Act (e.g. `healthy_homes` route targets `HHS2019`), that
+Act's search uses `boost_top_k` instead of `default_top_k`, giving it more candidates before ranking.
+
+Routes remain as hard floor guarantees - forced sections are always included in the candidate pool
+regardless of federated search results. This means a cross-encoder re-ranker (Phase 2) can
+reorder freely without risking that a critical section is dropped.
+
+A `CrossEncoderReranker` (Phase 1: log-only) is available in `core/reranker.py`. It scores
+candidates after federated search and logs the scores for observability without affecting ranking.
+Promote to production ranking after benchmarking shows it matches route-based quality.
+
+### Case retrieval augmentation (`case_synthetic_query` on `StatuteRoute`)
+
+When a matched route defines `case_synthetic_query`, a supplementary case retrieval pass
+runs with that query and unique results are merged into context (up to 8 total chunks).
+
+Fixes cases where the query rewriter drops legally significant framing that is obvious
+from the original question but lost in rewriting:
+
+```python
+StatuteRoute(
+    intent="sham_flatmate_agreement",
+    include_any=("flatmate agreement", "meant to be tenants", ...),
+    forced_sections=("NZLEG/RTA/s5",),
+    synthetic_query="...",
+    case_synthetic_query=(
+        "flatmate agreement landlord not living property sham tenancy RTA applies "
+        "boarder licensee residential tenancy act tenant rights eviction notice"
+    ),
+)
+```
+
+### Smoke fixture source count (`min_sources` on `SmokeFixture`)
+
+Assert that supplementary retrieval ran and returned the expected number of case sources:
+
+```python
+SmokeFixture(
+    question="My landlord put us on a flatmate agreement...",
+    expected_sections=[],
+    min_sources=6,
+    description="sham_flatmate_agreement route - case_synthetic_query augmentation",
+)
+```
+
+---
+
+## Qdrant payload schema
+
+All jurisdictions must produce chunks conforming to `schemas/qdrant_payload.schema.json`.
+
+Required fields: `document_id`, `court`, `court_name`, `title`, `date`, `url`, `text`, `source_type`.
+
+---
+
+## Stack
+
+| Component | Technology |
+|---|---|
+| Vector database | Qdrant |
+| Embeddings | nomic-embed-text-v1.5 / Qwen3-Embedding-0.6B via sentence-transformers |
+| LLM inference | llama.cpp (OpenAI-compatible) |
+| API | FastAPI + SSE streaming |
+| Cache | Redis (web verify results) |
+| Queue | Semaphore-based, per-IP fairness |
+
+---
+
+## Milestones
+
+- [x] Milestone 0 - core interface design, runtime modules, `nz_tenancy` jurisdiction
+- [x] Milestone 1 - `nsw_tenancy` skeleton + `nz_legal` + `nz_employment` prove interface generalises
+- [x] Milestone 2 - smoke test runner wired to pytest (Tier 1/2/3), Docker Compose
+- [x] Milestone 3 - CONTRIBUTING.md, packaging, NSW NCAT scraper + corpus (225+ decisions)
+- [x] Milestone 4 - `nz_legal` migration: tracker endpoints, contrasting cases, `register_routes` hook
+- [x] Milestone 5 - federated per-Act legislation retrieval, Healthy Homes Standards 2019 corpus, cross-encoder reranker (Phase 1 log-only), Qdrant payload indexes for fast filtered search
+
+---
+
+## Related project
+
+The NZ tenancy tool running on this framework: https://tenancy.localrun.ai
+
+Source: https://github.com/jwongso/nz-legal-rag
+
+---
+
+MIT License. Not legal advice.

astraea_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+astraea_framework-0.1.0.dist-info/licenses/LICENSE,sha256=buYdy5JwGudTRS33aMwE2HvaDg707r0ZEwxznPTeyB8,1076
+core/__init__.py,sha256=c9lekMTB52ytmIGeBRtbyLuMFh5mE5TdZ3ZRzu7BxHM,45
+core/api.py,sha256=YYlSaFkc48aieYE0Q0puCxUKK9ORczEsXcsM5yxV_lA,40360
+core/browser.py,sha256=_2HTBJs3ebgK9XiW0z4b7iRoq7XzpwqymNweSMM_II0,3765
+core/embedder.py,sha256=8eNT0uPmo_58IFrUCqCfsrfABQyKnIkroO8eXF8QPyM,3246
+core/feedback.py,sha256=LNSbO4c1XdZQvPOlNSFDIuHn2ooHb_k6n1n8x0CYm8Q,2830
+core/generator.py,sha256=labRa4c0_aX7PvwoABwcb7jGdLms_vsOlYwYxFS-u_Q,2705
+core/jurisdiction.py,sha256=nZDT511F9XQXTj1HYmFAVAKoNHGF2W3tRN2_8sk-t0c,8600
+core/legislation.py,sha256=I65anLF3FDdU_iZkda0Riq8gHEihKd0IVclQCecrOwk,4330
+core/mcp.py,sha256=Gp8D0FsncgRV9VgB0hJIGdfhKIXWmH8Wt2YAzEuyPN0,7654
+core/pipeline.py,sha256=5LX-KfJ0MvgeHajB0Qqoe53ZqvfxdqUAlczC3xEdS40,3315
+core/queue.py,sha256=PfGpiuBfDpqFfwrr7grDgj-TahxZqkOa6iaeHWYZcDY,5574
+core/reranker.py,sha256=ZISSqRJ7CU0CjUhyRMHAWZtLxHKVG8vEJGOV3Rx_o2U,2979
+core/retriever.py,sha256=jNC3QOweBrfUxbD6YRopB3Q77rlD-Pcdw4C9v5Mo5bc,6483
+core/routing.py,sha256=7Q_Tbcx6aK0QnnC0n8fZZryzgnIgvW-0ENxWnlKG5hk,2825
+core/sanitize.py,sha256=ECD5t8x01ODaBz7x1GlHQ5AI1t6tWCu8UxR_2U4JOzc,3194
+core/security.py,sha256=CyGWGaVweG3ZfLT6OOxS3P9a-8auSAC0nb1ts4oNBb0,1493
+core/service.py,sha256=5FlkZvK_SoXauomwPC3XiqwKPwqA4Q5jbexJ8aHJ_1A,6351
+examples/minimal_jurisdiction/__init__.py,sha256=wTjJOApiNu8cyG5gFH1OTm7yNKZ6iuuu7qMITQukO4Y,96
+examples/minimal_jurisdiction/jurisdiction.py,sha256=qDoc6tRWPAKCqgFdNpTjL-oiVQ7uznDSoLVFzGy0WL0,925
+ingest/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ingest/base.py,sha256=unlwS8rDDNL2NXg7dAUM6TFN7MqBafEuD-D3b1X1vBs,2615
+ingest/run_nsw_tenancy.py,sha256=VoDiXzZOWU6PtSAejgf18dC2M7ZkWkdX3J2IcGztCuo,3787
+jurisdictions/__init__.py,sha256=c9lekMTB52ytmIGeBRtbyLuMFh5mE5TdZ3ZRzu7BxHM,45
+jurisdictions/nsw_tenancy/__init__.py,sha256=0QgKqa5OifEl056__N0N8Rgn69DKHpHrJ3oSRL9gdI4,115
+jurisdictions/nsw_tenancy/jurisdiction.py,sha256=rvlS70fTetsg5-YNXjA172Z2j4boJ5c3a8VRSwB8fos,3679
+jurisdictions/nsw_tenancy/prompt.py,sha256=1eFK5IN86oS53QmbxXBC5aFfSqEX9rpTzkBROzESmok,1433
+jurisdictions/nsw_tenancy/routes.py,sha256=BQY0DSuhjavcfdUELyj7NB4H8XjPnFekHaez0kiUAFM,4428
+jurisdictions/nsw_tenancy/scraper.py,sha256=E8UBAXIZqU2yhduhl0BeO2SWN2cxSgfymR0bSlJ_lYA,6433
+jurisdictions/nz_employment/__init__.py,sha256=0gwVh9bg8HtxNhroABHnA752jDU8rKhh8SjCWkGLzLk,121
+jurisdictions/nz_employment/jurisdiction.py,sha256=wlNyr0Hk09nZxZ9zwy20j3Lrx02FgQY6Wax3FL6byRg,4201
+jurisdictions/nz_employment/prompt.py,sha256=GJlhwRKZAjKlgybqBmhVCDbgCq2vlTsnaXIIHZbamas,1804
+jurisdictions/nz_employment/routes.py,sha256=UQOZPtJrqqldT_G6CNC8DtdVVV-iHWb1pf21HW9i4sQ,4800
+jurisdictions/nz_legal/__init__.py,sha256=FrljWpT41T82ozAkGsz-k39Opn8j5d6f-7oFTI9FP8w,106
+jurisdictions/nz_legal/app.py,sha256=HjRbjlTawB9izFz7DZ0nCgI6QMfxyxoT94ZXSpPHIiE,141
+jurisdictions/nz_legal/contrasting.py,sha256=DXUh3OiEqHhZ6nOBqXp_G0aiJk2nN-botd2xO1JyQGA,7563
+jurisdictions/nz_legal/jurisdiction.py,sha256=78O2R1bIt8Ra6LzP08Ypbk1hpS5OOnEf0LC5TgezHb8,3942
+jurisdictions/nz_legal/routes.py,sha256=Ae-10G_lhliqrh_MTzFSSNFBPmjhMUa-l_h0jIGn6O8,10787
+jurisdictions/nz_legal/scroll.py,sha256=4I3RW22oS9RerIzH2wzNtnIaY-qQxIS3BVvRrIxp3xk,10845
+jurisdictions/nz_tenancy/__init__.py,sha256=x8Ta9elz_-A119SMp_-YWHewKDjWUbW1Z5kUqdiFa9M,112
+jurisdictions/nz_tenancy/jurisdiction.py,sha256=AEzUJv5HcxMknFQc0Wzv6YWfTFRP-8VgDFe1aWI7lkk,6760
+jurisdictions/nz_tenancy/mcp_server.py,sha256=USfRLsvTnMk93-lBrhqOrGa32PZHTrYai1xOVOnwvW0,935
+jurisdictions/nz_tenancy/prompt.py,sha256=38PDP6Fqh4dTWQGNLuNR5dn9bYyQx-aru4lqOz1H540,7510
+jurisdictions/nz_tenancy/routes.py,sha256=uZb0N5hAx4WKN_IQXT5r97DpT4rAa-29_XMnxqth0rE,9832
+jurisdictions/nz_tenancy/scraper.py,sha256=F17afOMJFtPxfNR8FPw9W7b4BZ5cHJxsJvXUonqv89Y,247
+astraea_framework-0.1.0.dist-info/METADATA,sha256=cs7Z6Rq3yqIEaTeGM3l666q90Upf60GJwGWTlDozB-0,8757
+astraea_framework-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+astraea_framework-0.1.0.dist-info/top_level.txt,sha256=AZGdbLZ14EMCesgcPBSe9qPAm93SiRYk2WZa93CY1wQ,35
+astraea_framework-0.1.0.dist-info/RECORD,,

astraea_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

astraea_framework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsaputra@riseup.net
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

astraea_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+core
+examples
+ingest
+jurisdictions

core/__init__.py

@@ -0,0 +1 @@
+# TODO: Milestone 0 - port from nz-legal-rag