"""HTTP API for the research-workspace entities (projects, links, questions...)."""
from __future__ import annotations
from typing import List, Optional
from fastapi import APIRouter, Query
from pydantic import BaseModel, Field
from atlas.core.errors import ConflictError
from atlas.db.projects import ProjectRepository
from review.settings import ReviewPaths
router = APIRouter(prefix="/api/projects", tags=["projects"])
def _repo() -> ProjectRepository:
paths = ReviewPaths.build()
paths.ensure()
return ProjectRepository(paths.db_path)
class ProjectCreate(BaseModel):
name: str = Field(min_length=1, max_length=160)
description: str = Field(default="", max_length=4000)
background: str = Field(default="", max_length=8000)
objectives: str = Field(default="", max_length=8000)
keywords: List[str] = Field(default_factory=list, max_length=50)
directions: List[str] = Field(default_factory=list, max_length=50)
color: str = Field(default="", max_length=32)
icon: str = Field(default="", max_length=16)
cover_path: str = Field(default="", max_length=500)
research_status: str = Field(default="active", max_length=16)
class ProjectUpdate(BaseModel):
name: Optional[str] = Field(default=None, min_length=1, max_length=160)
description: Optional[str] = Field(default=None, max_length=4000)
background: Optional[str] = Field(default=None, max_length=8000)
objectives: Optional[str] = Field(default=None, max_length=8000)
keywords: Optional[List[str]] = Field(default=None, max_length=50)
directions: Optional[List[str]] = Field(default=None, max_length=50)
color: Optional[str] = Field(default=None, max_length=32)
icon: Optional[str] = Field(default=None, max_length=16)
cover_path: Optional[str] = Field(default=None, max_length=500)
status: Optional[str] = Field(default=None, max_length=16)
research_status: Optional[str] = Field(default=None, max_length=16)
sort_order: Optional[int] = None
class PaperLinkCreate(BaseModel):
doi: str = Field(min_length=5, max_length=300)
role: str = Field(default="general", max_length=16)
reading_status: str = Field(default="unread", max_length=16)
priority: int = 0
project_note: str = Field(default="", max_length=4000)
evaluation: str = Field(default="", max_length=4000)
rating: Optional[int] = Field(default=None, ge=0, le=5)
tags: List[str] = Field(default_factory=list, max_length=30)
class PaperLinkUpdate(BaseModel):
role: Optional[str] = Field(default=None, max_length=16)
reading_status: Optional[str] = Field(default=None, max_length=16)
priority: Optional[int] = None
project_note: Optional[str] = Field(default=None, max_length=4000)
evaluation: Optional[str] = Field(default=None, max_length=4000)
rating: Optional[int] = Field(default=None, ge=0, le=5)
tags: Optional[List[str]] = Field(default=None, max_length=30)
relevance_score: Optional[float] = None
relevance_reason: Optional[str] = Field(default=None, max_length=2000)
class QuestionCreate(BaseModel):
question: str = Field(min_length=1, max_length=4000)
description: str = Field(default="", max_length=8000)
hypothesis: str = Field(default="", max_length=4000)
keywords: List[str] = Field(default_factory=list, max_length=30)
paper_dois: List[str] = Field(default_factory=list, max_length=100)
status: str = Field(default="open", max_length=16)
origin: str = Field(default="user", max_length=16)
doi: str = Field(default="", max_length=300)
parent_id: Optional[int] = None
class QuestionUpdate(BaseModel):
question: Optional[str] = Field(default=None, max_length=4000)
description: Optional[str] = Field(default=None, max_length=8000)
hypothesis: Optional[str] = Field(default=None, max_length=4000)
keywords: Optional[List[str]] = Field(default=None, max_length=30)
paper_dois: Optional[List[str]] = Field(default=None, max_length=100)
status: Optional[str] = Field(default=None, max_length=16)
sort_order: Optional[int] = None
class ProgressCreate(BaseModel):
title: str = Field(min_length=1, max_length=300)
content_md: str = Field(default="", max_length=200000)
kind: str = Field(default="log", max_length=16)
progress_percent: Optional[int] = Field(default=None, ge=0, le=100)
occurred_at: str = Field(default="", max_length=64)
class NoteCreate(BaseModel):
title: str = Field(default="", max_length=300)
content_md: str = Field(default="", max_length=200000)
kind: str = Field(default="note", max_length=16)
doi: str = Field(default="", max_length=300)
page_from: Optional[int] = None
page_to: Optional[int] = None
@router.get("")
def list_projects(include_archived: bool = False, q: str = ""):
return {"items": _repo().list_projects(include_archived=include_archived, query=q)}
@router.post("", status_code=201)
def create_project(payload: ProjectCreate):
return _repo().create_project(**payload.model_dump())
@router.get("/{project_id}")
def get_project(project_id: int):
return _repo().get_project(project_id)
@router.patch("/{project_id}")
def update_project(project_id: int, payload: ProjectUpdate):
return _repo().update_project(project_id, **payload.model_dump(exclude_unset=True))
@router.delete("/{project_id}")
def delete_project(project_id: int, confirm: bool = False):
repo = _repo()
if not confirm:
summary = repo.project_deletion_summary(project_id)
raise ConflictError(
"deleting a project removes its links, questions, notes and progress; "
"pass confirm=true after reviewing the summary",
details={"project_id": project_id, "will_delete": summary},
)
repo.delete_project(project_id)
return {"ok": True}
@router.get("/{project_id}/papers")
def list_project_papers(project_id: int, role: str = "", reading_status: str = "",
q: str = "", year: str = "", tag: str = "",
has_analysis: Optional[bool] = None,
limit: int = Query(default=200, ge=1, le=500),
offset: int = Query(default=0, ge=0)):
return _repo().list_papers(project_id, role=role, reading_status=reading_status,
query=q, year=year, tag=tag, has_analysis=has_analysis,
limit=limit, offset=offset)
@router.get("/{project_id}/papers/available")
def list_available_papers(project_id: int, q: str = "",
limit: int = Query(default=50, ge=1, le=200)):
return _repo().list_available_papers(project_id, query=q, limit=limit)
@router.post("/{project_id}/papers", status_code=201)
def link_paper(project_id: int, payload: PaperLinkCreate):
return _repo().link_paper(project_id, payload.doi, role=payload.role,
reading_status=payload.reading_status,
priority=payload.priority, project_note=payload.project_note,
evaluation=payload.evaluation, rating=payload.rating,
tags=payload.tags)
@router.patch("/{project_id}/papers/{doi:path}")
def update_paper_link(project_id: int, doi: str, payload: PaperLinkUpdate):
return _repo().update_paper_link(project_id, doi, **payload.model_dump(exclude_unset=True))
@router.delete("/{project_id}/papers/{doi:path}")
def unlink_paper(project_id: int, doi: str):
_repo().unlink_paper(project_id, doi)
return {"ok": True}
@router.get("/{project_id}/questions")
def list_questions(project_id: int):
return {"items": _repo().list_questions(project_id)}
@router.post("/{project_id}/questions", status_code=201)
def create_question(project_id: int, payload: QuestionCreate):
repo = _repo()
return repo.create_question(project_id, question=payload.question,
description=payload.description, status=payload.status,
doi=payload.doi, parent_id=payload.parent_id,
hypothesis=payload.hypothesis, keywords=payload.keywords,
paper_dois=payload.paper_dois, origin=payload.origin)
@router.patch("/{project_id}/questions/{question_id}")
def update_question(project_id: int, question_id: int, payload: QuestionUpdate):
return _repo().update_question(question_id, **payload.model_dump(exclude_unset=True))
@router.delete("/{project_id}/questions/{question_id}")
def delete_question(project_id: int, question_id: int):
_repo().delete_question(question_id)
return {"ok": True}
@router.get("/{project_id}/progress")
def list_progress(project_id: int):
return {"items": _repo().list_progress(project_id)}
@router.post("/{project_id}/progress", status_code=201)
def create_progress(project_id: int, payload: ProgressCreate):
return _repo().create_progress(project_id, **payload.model_dump())
@router.get("/{project_id}/notes")
def list_notes(project_id: int, doi: str = ""):
return {"items": _repo().list_notes(project_id, doi=doi)}
@router.post("/{project_id}/notes", status_code=201)
def create_note(project_id: int, payload: NoteCreate):
return _repo().create_note(project_id, **payload.model_dump())
class NoteUpdate(BaseModel):
title: Optional[str] = Field(default=None, max_length=300)
content_md: Optional[str] = Field(default=None, max_length=200000)
kind: Optional[str] = Field(default=None, max_length=16)
page_from: Optional[int] = None
page_to: Optional[int] = None
@router.patch("/{project_id}/notes/{note_id}")
def update_note(project_id: int, note_id: int, payload: NoteUpdate):
return _repo().update_note(note_id, **payload.model_dump(exclude_unset=True))
@router.delete("/{project_id}/notes/{note_id}")
def delete_note(project_id: int, note_id: int):
_repo().delete_note(note_id)
return {"ok": True}