coronelli 0.1.0__py3-none-any.whl

app/api/admin.py

@@ -0,0 +1,20 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from app.db.engine import get_db
+from app.db.models import SourceDocument
+from app.domain.world import EntityMention, MapClaim, MapEntity, MapTravelRule
+
+router = APIRouter(tags=["admin"])
+
+
+@router.delete("/api/admin/reset", status_code=200)
+def reset_library(db: Session = Depends(get_db)) -> dict:
+    """Delete everything: all documents and all derived map data."""
+    db.query(MapClaim).delete(synchronize_session=False)
+    db.query(MapTravelRule).delete(synchronize_session=False)
+    db.query(EntityMention).delete(synchronize_session=False)
+    db.query(MapEntity).delete(synchronize_session=False)
+    db.query(SourceDocument).delete(synchronize_session=False)
+    db.commit()
+    return {"reset": True}

app/api/atlas.py

@@ -0,0 +1,15 @@
+from fastapi import APIRouter
+
+from app.api.atlas_edit import router as edit_router
+from app.api.atlas_export import router as export_router
+from app.api.atlas_hierarchy import router as hierarchy_router
+from app.api.atlas_read import router as read_router
+from app.api.atlas_suggestions import router as suggestions_router
+
+router = APIRouter(tags=["atlas"])
+
+router.include_router(read_router)
+router.include_router(export_router)
+router.include_router(edit_router)
+router.include_router(hierarchy_router)
+router.include_router(suggestions_router)

app/api/atlas_edit.py

@@ -0,0 +1,313 @@
+import uuid
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from app.api.atlas_read import ClaimOut, _provenance
+from app.db.engine import get_db
+from app.db.models import SourceSection
+from app.domain.world import MapClaim, MapEntity
+from app.extraction.models import Candidate, ExtractionRun
+
+router = APIRouter(tags=["atlas"])
+
+
+# ── Entity patch / delete ─────────────────────────────────────────────────────
+
+class EntityPatchRequest(BaseModel):
+    name: str | None = None
+    place_kind: str | None = None
+    tier: str | None = None
+    spatial_level: int | None = None
+
+
+@router.patch("/api/documents/{document_id}/atlas/entities/{entity_id}")
+def patch_atlas_entity(
+    document_id: str, entity_id: str, body: EntityPatchRequest, db: Session = Depends(get_db)
+):
+    from fastapi import HTTPException
+    from sqlalchemy.orm.attributes import flag_modified
+
+    entity = db.get(MapEntity, entity_id)
+    if not entity or entity.provenance_document_id != document_id:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    if body.name is not None:
+        new_name = body.name.strip()
+        if new_name and new_name != entity.name:
+            old_name = entity.name
+            entity.name = new_name
+            aliases = list(entity.aliases or [])
+            if old_name and old_name not in aliases:
+                aliases.insert(0, old_name)
+            entity.aliases = aliases
+            flag_modified(entity, "aliases")
+    if body.place_kind is not None:
+        entity.place_kind = body.place_kind
+    if body.tier is not None:
+        payload = dict(entity.payload or {})
+        if body.tier:
+            payload["tier"] = body.tier
+        else:
+            payload.pop("tier", None)
+        entity.payload = payload
+        flag_modified(entity, "payload")
+    if body.spatial_level is not None:
+        payload = dict(entity.payload or {})
+        if body.spatial_level >= 0:
+            payload["spatial_level"] = body.spatial_level
+        else:
+            payload.pop("spatial_level", None)
+        entity.payload = payload
+        flag_modified(entity, "payload")
+    entity.status = "manual"
+    db.commit()
+    return {"ok": True}
+
+
+@router.delete("/api/documents/{document_id}/atlas/entities/{entity_id}")
+def delete_atlas_entity(document_id: str, entity_id: str, db: Session = Depends(get_db)):
+    from fastapi import HTTPException
+
+    entity = db.get(MapEntity, entity_id)
+    if not entity or entity.provenance_document_id != document_id:
+        raise HTTPException(status_code=404, detail="Entity not found")
+    entity.state = "deleted"
+    for claim in db.query(MapClaim).filter(
+        MapClaim.subject_ref == entity_id,
+        MapClaim.state == "active",
+    ).all():
+        claim.state = "deleted"
+    for claim in db.query(MapClaim).filter(
+        MapClaim.provenance_document_id == document_id,
+        MapClaim.state == "active",
+    ).all():
+        if claim.object_refs and entity_id in claim.object_refs:
+            claim.state = "deleted"
+    db.commit()
+    return {"ok": True}
+
+
+# ── Claim patch / delete / create ─────────────────────────────────────────────
+
+class ClaimPatchRequest(BaseModel):
+    predicate: str | None = None
+    object_refs: list[str] | None = None
+
+
+class ClaimCreateRequest(BaseModel):
+    claim_type: str = "spatial"
+    predicate: str
+    subject_ref: str
+    object_refs: list[str]
+
+
+@router.patch("/api/documents/{document_id}/atlas/claims/{claim_id}")
+def patch_atlas_claim(
+    document_id: str, claim_id: str, body: ClaimPatchRequest, db: Session = Depends(get_db)
+):
+    from fastapi import HTTPException
+
+    claim = db.get(MapClaim, claim_id)
+    if not claim or claim.provenance_document_id != document_id or claim.state != "active":
+        raise HTTPException(status_code=404, detail="Claim not found")
+    if body.predicate is not None:
+        claim.predicate = body.predicate
+    if body.object_refs is not None:
+        claim.object_refs = body.object_refs
+    claim.status = "manual"
+    db.commit()
+    return {"ok": True}
+
+
+@router.delete("/api/documents/{document_id}/atlas/claims/{claim_id}")
+def delete_atlas_claim(document_id: str, claim_id: str, db: Session = Depends(get_db)):
+    from fastapi import HTTPException
+
+    claim = db.get(MapClaim, claim_id)
+    if not claim or claim.provenance_document_id != document_id:
+        raise HTTPException(status_code=404, detail="Claim not found")
+    claim.state = "deleted"
+    db.commit()
+    return {"ok": True}
+
+
+@router.post("/api/documents/{document_id}/atlas/claims", response_model=ClaimOut)
+def create_atlas_claim(document_id: str, body: ClaimCreateRequest, db: Session = Depends(get_db)):
+    claim = MapClaim(
+        id=str(uuid.uuid4()),
+        claim_type=body.claim_type,
+        predicate=body.predicate,
+        subject_ref=body.subject_ref,
+        object_refs=body.object_refs,
+        provenance_document_id=document_id,
+        provenance_section_id=None,
+        payload={},
+        confidence=1.0,
+        excerpt="",
+        status="manual",
+        state="active",
+    )
+    db.add(claim)
+    db.commit()
+    db.refresh(claim)
+    return ClaimOut(
+        id=claim.id,
+        claim_type=claim.claim_type,
+        predicate=claim.predicate,
+        subject_ref=claim.subject_ref,
+        object_refs=claim.object_refs,
+        payload=claim.payload,
+        confidence=claim.confidence,
+        excerpt=claim.excerpt,
+        status=claim.status,
+        provenance=_provenance(claim.provenance_document_id, claim.provenance_section_id),
+    )
+
+
+# ── Manual entity creation ─────────────────────────────────────────────────────
+
+class ManualEntityRequest(BaseModel):
+    name: str
+    type: str | None = None
+    spatial_level: int | None = None
+
+
+class ManualEntityResponse(BaseModel):
+    id: str
+    name: str
+
+
+@router.post("/api/documents/{document_id}/manual-entity", response_model=ManualEntityResponse)
+def add_manual_entity(document_id: str, body: ManualEntityRequest, db: Session = Depends(get_db)):
+    from fastapi import HTTPException
+
+    if not body.name or not body.name.strip():
+        raise HTTPException(status_code=422, detail="name is required")
+
+    first_section = (
+        db.query(SourceSection)
+        .filter(SourceSection.document_id == document_id)
+        .order_by(SourceSection.ordinal)
+        .first()
+    )
+    if not first_section:
+        raise HTTPException(status_code=404, detail="Document has no sections")
+
+    stub_run = (
+        db.query(ExtractionRun)
+        .filter(
+            ExtractionRun.section_id == first_section.id,
+            ExtractionRun.status == "manual",
+        )
+        .first()
+    )
+    if not stub_run:
+        now = datetime.now(timezone.utc)
+        stub_run = ExtractionRun(
+            section_id=first_section.id,
+            status="manual",
+            provider="manual",
+            model="manual",
+            prompt_version="manual-entry",
+            started_at=now,
+            completed_at=now,
+        )
+        db.add(stub_run)
+        db.flush()
+
+    payload: dict = {"name": body.name.strip(), "type": body.type or "place", "aliases": []}
+    if body.spatial_level is not None:
+        payload["spatial_level"] = body.spatial_level
+
+    candidate = Candidate(
+        extraction_run_id=stub_run.id,
+        section_id=first_section.id,
+        kind="entity",
+        payload=payload,
+        status="explicit",
+        confidence=1.0,
+        excerpt="",
+        rationale="Manually added by user",
+        review_state="approved",
+        ordinal=9999,
+        source="manual",
+    )
+    db.add(candidate)
+    db.commit()
+
+    return ManualEntityResponse(id=candidate.id, name=body.name.strip())
+
+
+# ── Entity merge ───────────────────────────────────────────────────────────────
+
+class EntityMergeRequest(BaseModel):
+    keep_id: str
+    drop_id: str
+
+
+class EntityMergeResponse(BaseModel):
+    merged: bool
+    canonical_entity_id: str
+    canonical_entity_name: str
+    new_aliases: list[str]
+
+
+@router.post("/api/entities/merge", response_model=EntityMergeResponse)
+def merge_entities(body: EntityMergeRequest, db: Session = Depends(get_db)):
+    from fastapi import HTTPException
+
+    keep = db.get(MapEntity, body.keep_id)
+    drop = db.get(MapEntity, body.drop_id)
+    if not keep or not drop:
+        raise HTTPException(status_code=404, detail="One or both entities not found")
+    if keep.id == drop.id:
+        raise HTTPException(status_code=422, detail="Cannot merge an entity with itself")
+    if keep.state != "active" or drop.state != "active":
+        raise HTTPException(status_code=422, detail="Both entities must be active")
+
+    new_aliases = list(keep.aliases or [])
+    for name in [drop.name, *(drop.aliases or [])]:
+        if name and name != keep.name and name not in new_aliases:
+            new_aliases.append(name)
+    keep.aliases = new_aliases
+
+    db.query(MapClaim).filter(
+        MapClaim.subject_ref == body.drop_id,
+        MapClaim.state == "active",
+    ).update({"subject_ref": body.keep_id}, synchronize_session=False)
+
+    object_claims = db.query(MapClaim).filter(MapClaim.state == "active").all()
+    for c in object_claims:
+        if c.object_refs and body.drop_id in c.object_refs:
+            c.object_refs = [body.keep_id if r == body.drop_id else r for r in c.object_refs]
+
+    drop.state = "merged"
+
+    _existing_same_as = db.query(MapClaim).filter(
+        MapClaim.subject_ref == keep.id,
+        MapClaim.predicate == "SAME_AS",
+        MapClaim.state == "active",
+    ).all()
+    if not any(c.object_refs and drop.id in c.object_refs for c in _existing_same_as):
+        db.add(MapClaim(
+            claim_type="spatial",
+            subject_ref=keep.id,
+            predicate="SAME_AS",
+            object_refs=[drop.id],
+            status="manual",
+            state="active",
+            provenance_document_id=keep.provenance_document_id,
+            payload={"subject": keep.name, "object": drop.name, "predicate": "SAME_AS"},
+        ))
+
+    db.commit()
+    db.refresh(keep)
+
+    return EntityMergeResponse(
+        merged=True,
+        canonical_entity_id=keep.id,
+        canonical_entity_name=keep.name,
+        new_aliases=new_aliases,
+    )

app/api/atlas_export.py

@@ -0,0 +1,331 @@
+import re
+import uuid
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+from sqlalchemy.orm import Session
+
+from app.api.atlas_read import _discovery, _provenance
+from app.db.engine import get_db
+from app.db.models import SourceDocument, SourceSection
+from app.domain.world import MapClaim, MapEntity, MapTravelRule
+from app.extraction.models import Candidate
+
+router = APIRouter(tags=["atlas"])
+
+
+@router.get("/api/documents/{document_id}/atlas.json")
+def export_atlas_json(document_id: str, db: Session = Depends(get_db)) -> JSONResponse:
+    doc = db.get(SourceDocument, document_id)
+
+    entities = (
+        db.query(MapEntity)
+        .filter(MapEntity.provenance_document_id == document_id, MapEntity.state == "active")
+        .order_by(MapEntity.name)
+        .all()
+    )
+    all_claims = (
+        db.query(MapClaim)
+        .filter(MapClaim.provenance_document_id == document_id, MapClaim.state == "active")
+        .all()
+    )
+    travel_rules = (
+        db.query(MapTravelRule)
+        .filter(MapTravelRule.provenance_document_id == document_id, MapTravelRule.state == "active")
+        .all()
+    )
+
+    active_entity_ids = {e.id for e in entities}
+    entity_by_id = {e.id: e for e in entities}
+
+    located_in: dict[str, str] = {}
+    for claim in sorted(all_claims, key=lambda c: 1 if c.status == "manual" else 0):
+        if claim.predicate == "CONTAINS":
+            if claim.object_refs and claim.object_refs[0] in active_entity_ids:
+                contained_id = claim.object_refs[0]
+                if claim.subject_ref in entity_by_id:
+                    located_in[contained_id] = entity_by_id[claim.subject_ref].name
+        elif claim.predicate == "LOCATED_IN" or claim.predicate == "PART_OF":
+            if claim.subject_ref in active_entity_ids and claim.object_refs:
+                container_id = claim.object_refs[0]
+                if container_id in entity_by_id:
+                    located_in[claim.subject_ref] = entity_by_id[container_id].name
+
+    _sections = db.query(SourceSection).filter(SourceSection.document_id == document_id).all()
+    section_ids = {s.id for s in _sections}
+    section_by_id = {s.id: s for s in _sections}
+    entity_candidates = (
+        db.query(Candidate)
+        .filter(
+            Candidate.kind == "entity",
+            Candidate.status != "rejected",
+            Candidate.excerpt != "",
+            Candidate.section_id.in_(section_ids),
+        )
+        .order_by(Candidate.ordinal)
+        .all()
+    )
+    excerpt_by_name: dict[str, str] = {}
+    for cand in entity_candidates:
+        cname = (cand.payload or {}).get("name", "").lower()
+        if cname and cname not in excerpt_by_name and cand.excerpt:
+            excerpt_by_name[cname] = cand.excerpt.strip()
+
+    def _first_excerpt(entity: MapEntity) -> str | None:
+        exc = excerpt_by_name.get(entity.name.lower())
+        if exc:
+            return exc
+        for alias in (entity.aliases or []):
+            exc = excerpt_by_name.get(alias.lower())
+            if exc:
+                return exc
+        return None
+
+    def _id_to_name(eid: str | None) -> str | None:
+        return entity_by_id[eid].name if eid and eid in entity_by_id else None
+
+    world_entities = [
+        {
+            "id": e.id,
+            "name": e.name,
+            "kind": e.place_kind,
+            "kind_descriptor": (e.payload or {}).get("kind_descriptor"),
+            "tier": (e.payload or {}).get("tier"),
+            "spatial_level": (e.payload or {}).get("spatial_level"),
+            "colors": (e.payload or {}).get("colors"),
+            "aliases": list(e.aliases or []),
+            "located_in": located_in.get(e.id),
+            "excerpt": _first_excerpt(e),
+            "anchor_count": (e.payload or {}).get("anchor_count", 0),
+            "narrative_roles": (e.payload or {}).get("narrative_roles", []),
+            "significance": (e.payload or {}).get("significance"),
+            "description": (e.payload or {}).get("description"),
+            "observations": (e.payload or {}).get("observations", []),
+            "first_seen": {
+                "section_id": e.provenance_section_id,
+                "section_title": section_by_id[e.provenance_section_id].title
+                    if e.provenance_section_id in section_by_id else None,
+                "section_ordinal": section_by_id[e.provenance_section_id].ordinal
+                    if e.provenance_section_id in section_by_id else None,
+            } if e.provenance_section_id else None,
+        }
+        for e in entities
+    ]
+
+    spatial_claims = []
+    visual_claims = []
+    for c in all_claims:
+        if not c.subject_ref or not c.predicate:
+            continue
+        object_id = c.object_refs[0] if c.object_refs else None
+        if c.claim_type == "spatial":
+            spatial_claims.append({
+                "id": c.id,
+                "subject": _id_to_name(c.subject_ref) or c.payload.get("subject"),
+                "predicate": c.predicate,
+                "object": _id_to_name(object_id) or c.payload.get("object"),
+                "bidirectional": c.payload.get("bidirectional"),
+                "confidence": c.confidence,
+                "status": c.status,
+                "excerpt": c.excerpt,
+            })
+        elif c.claim_type == "visual":
+            visual_claims.append({
+                "id": c.id,
+                "subject": _id_to_name(c.subject_ref) or c.payload.get("subject"),
+                "visual_property": c.payload.get("visual_property") or c.payload.get("category", ""),
+                "value": c.payload.get("value") or c.payload.get("observation", ""),
+                "section_title": c.payload.get("section_title", ""),
+                "palette": c.payload.get("palette"),
+                "permanent": c.payload.get("permanent"),
+                "view": c.payload.get("view"),
+                "confidence": c.confidence,
+                "status": c.status,
+            })
+
+    routes = [
+        {
+            "id": r.id,
+            "traveler": r.traveler,
+            "from": r.payload.get("from"),
+            "to": r.payload.get("to"),
+            "via": r.payload.get("via"),
+            "can_traverse": r.can_traverse,
+            "condition": r.condition,
+            "bidirectional": r.payload.get("bidirectional"),
+            "transport_mode": r.payload.get("transport_mode"),
+            "notes": r.payload.get("notes"),
+        }
+        for r in travel_rules
+    ]
+
+    package = {
+        "format": "coronelli-atlas-v1",
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "document": {
+            "id": document_id,
+            "title": doc.title if doc else document_id,
+        },
+        "entities": world_entities,
+        "spatial_claims": spatial_claims,
+        "visual_claims": visual_claims,
+        "routes": routes,
+    }
+
+    raw_slug = re.sub(r'[^a-z0-9]+', '-', (doc.title if doc else document_id).lower()).strip('-')
+    filename = f"atlas-{raw_slug[:40]}.json"
+    return JSONResponse(
+        content=package,
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.get("/api/documents/{document_id}/atlas-package")
+def export_atlas_package(document_id: str, db: Session = Depends(get_db)) -> JSONResponse:
+    doc = db.get(SourceDocument, document_id)
+
+    sections = (
+        db.query(SourceSection)
+        .filter(SourceSection.document_id == document_id)
+        .order_by(SourceSection.ordinal)
+        .all()
+    )
+
+    entities = (
+        db.query(MapEntity)
+        .filter(MapEntity.provenance_document_id == document_id, MapEntity.state == "active")
+        .order_by(MapEntity.name)
+        .all()
+    )
+    all_claims = (
+        db.query(MapClaim)
+        .filter(MapClaim.provenance_document_id == document_id, MapClaim.state == "active")
+        .all()
+    )
+    travel_rules = (
+        db.query(MapTravelRule)
+        .filter(MapTravelRule.provenance_document_id == document_id, MapTravelRule.state == "active")
+        .all()
+    )
+
+    entity_by_id: dict[str, MapEntity] = {e.id: e for e in entities}
+    entity_id_by_name: dict[str, str] = {e.name.lower(): e.id for e in entities}
+    for e in entities:
+        for alias in (e.aliases or []):
+            if alias.lower() not in entity_id_by_name:
+                entity_id_by_name[alias.lower()] = e.id
+
+    def _name_to_id(name: str | None) -> str | None:
+        return entity_id_by_name.get(name.lower()) if name else None
+
+    def _id_to_name(entity_id: str | None) -> str | None:
+        return entity_by_id[entity_id].name if entity_id and entity_id in entity_by_id else None
+
+    manifest = {
+        "package_id": str(uuid.uuid4()),
+        "format_version": "atlas-package-v0.1",
+        "profile": "single-file-json",
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "generator": "coronelli",
+        "entity_count": len(entities),
+        "claim_count": len(all_claims),
+        "route_count": len(travel_rules),
+        "source_count": 1,
+    }
+
+    sources = [
+        {
+            "document_id": document_id,
+            "title": doc.title if doc else document_id,
+            "sections": [
+                {
+                    "section_id": s.id,
+                    "ordinal": s.ordinal,
+                    "title": s.title,
+                }
+                for s in sections
+            ],
+        }
+    ]
+
+    world_entities = []
+    for e in entities:
+        world_entities.append({
+            "id": e.id,
+            "name": e.name,
+            "type": e.place_kind,
+            "aliases": list(e.aliases or []),
+            "status": e.status,
+            "provenance": _provenance(e.provenance_document_id, e.provenance_section_id),
+            "discovery": _discovery(e),
+            "notes": e.payload.get("notes"),
+        })
+
+    spatial_claims = []
+    visual_claims = []
+    for c in all_claims:
+        object_id = c.object_refs[0] if c.object_refs else None
+        prov = _provenance(c.provenance_document_id, c.provenance_section_id)
+
+        if c.claim_type == "spatial":
+            spatial_claims.append({
+                "id": c.id,
+                "subject_id": c.subject_ref,
+                "subject_name": _id_to_name(c.subject_ref) or c.payload.get("subject"),
+                "predicate": c.predicate or c.payload.get("predicate"),
+                "object_id": object_id,
+                "object_name": _id_to_name(object_id) or c.payload.get("object"),
+                "status": c.status,
+                "confidence": c.confidence,
+                "provenance": prov,
+                "excerpt": c.excerpt,
+            })
+        elif c.claim_type == "visual":
+            visual_claims.append({
+                "id": c.id,
+                "subject_id": c.subject_ref,
+                "subject_name": _id_to_name(c.subject_ref) or c.payload.get("subject"),
+                "visual_property": c.payload.get("visual_property") or c.payload.get("category", ""),
+                "value": c.payload.get("value") or c.payload.get("observation", ""),
+                "status": c.status,
+                "provenance": prov,
+            })
+
+    world_routes = []
+    for r in travel_rules:
+        from_name = r.payload.get("from")
+        to_name = r.payload.get("to")
+        via_name = r.payload.get("via")
+        world_routes.append({
+            "id": r.id,
+            "traveler": r.traveler,
+            "from_id": _name_to_id(from_name),
+            "from_name": from_name,
+            "to_id": _name_to_id(to_name),
+            "to_name": to_name,
+            "via_id": _name_to_id(via_name),
+            "via_name": via_name,
+            "can_traverse": r.can_traverse,
+            "condition": r.condition,
+            "provenance": _provenance(r.provenance_document_id, r.provenance_section_id),
+        })
+
+    package = {
+        "format": "atlas-package-v0.1-single",
+        "manifest": manifest,
+        "sources": sources,
+        "world": {
+            "entities": world_entities,
+            "spatial_claims": spatial_claims,
+            "visual_claims": visual_claims,
+            "routes": world_routes,
+        },
+    }
+
+    slug = (doc.title if doc else document_id)[:32].replace(" ", "-").lower()
+    filename = f"atlas-{slug}-v0.1.json"
+    return JSONResponse(
+        content=package,
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )