knowledge-os-mcp-server 0.3.1__py3-none-any.whl

knowledge_os/__init__.py

@@ -0,0 +1,3 @@
+"""MCP Knowledge OS."""
+
+__version__ = "0.3.1"

knowledge_os/api/deps.py

@@ -0,0 +1,13 @@
+"""Dependências FastAPI: a conexão do request."""
+
+from fastapi import Header
+
+from knowledge_os.storage.access import resolve_connection
+
+
+def get_connection_id(x_connection_id: str | None = Header(default=None)) -> str:
+    """Conexão dos dados: o header X-Connection-Id ou, sem ele, a padrão do connections.json.
+
+    422 se não há conexão configurada ou se ela está desabilitada; 404 se não existe.
+    """
+    return resolve_connection(x_connection_id).id

knowledge_os/api/main.py

@@ -0,0 +1,112 @@
+"""App FastAPI do Knowledge OS: camada HTTP sobre os services."""
+
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from knowledge_os import __version__
+from knowledge_os.api.routes import (
+    connection,
+    item,
+    project,
+    relation,
+    tag,
+    workspace,
+)
+from knowledge_os.exceptions import NotFoundError, StorageError, ValidationError
+
+app = FastAPI(
+    title="Knowledge OS API",
+    version=__version__,
+    description="REST API para Knowledge OS MCP",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/api/openapi.json",
+)
+
+# Sem login: o servidor é local (127.0.0.1). Sem CORS: a UI é servida pela mesma origem.
+# TrustedHost barra DNS rebinding (Host forjado); "testserver" é o host do TestClient.
+app.add_middleware(
+    TrustedHostMiddleware, allowed_hosts=["127.0.0.1", "localhost", "testserver"]
+)
+
+_WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+
+@app.middleware("http")
+async def _same_origin_writes(request: Request, call_next):
+    """Recusa escrita vinda de outra página: o navegador manda `Origin` e ele deve ser o do Host.
+
+    Sem `Origin` (curl, scripts, TestClient) a requisição passa: só o navegador é o vetor.
+    """
+    origin = request.headers.get("origin")
+    if request.method in _WRITE_METHODS and origin is not None:
+        if origin == "null" or urlsplit(origin).netloc != request.headers.get("host", ""):
+            return JSONResponse(status_code=403, content={"detail": "Origin não permitida"})
+    return await call_next(request)
+
+
+_SECURITY_HEADERS = {
+    "X-Frame-Options": "DENY",
+    "X-Content-Type-Options": "nosniff",
+    # Tudo servido daqui (sem CDN). 'unsafe-eval': o Alpine avalia as expressões dos atributos;
+    # style 'unsafe-inline': atributos style do HTML.
+    "Content-Security-Policy": (
+        "default-src 'self'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; "
+        "img-src 'self' data:; font-src 'self' data:; connect-src 'self'; object-src 'none'; "
+        "base-uri 'self'; frame-ancestors 'none'; form-action 'self'"
+    ),
+}
+
+
+@app.middleware("http")
+async def _security_headers(request: Request, call_next):
+    response = await call_next(request)
+    for name, value in _SECURITY_HEADERS.items():
+        response.headers[name] = value
+    if request.url.path.startswith("/ui"):
+        # Módulos ES sem build: sem isso o navegador mistura versões em cache depois de uma
+        # atualização (import de export inexistente = tela preta). Revalida por ETag (304).
+        response.headers["Cache-Control"] = "no-cache"
+    return response
+
+
+@app.exception_handler(NotFoundError)
+async def _not_found(_: Request, exc: NotFoundError) -> JSONResponse:
+    return JSONResponse(status_code=404, content={"detail": str(exc)})
+
+
+@app.exception_handler(ValidationError)
+async def _validation(_: Request, exc: ValidationError) -> JSONResponse:
+    return JSONResponse(status_code=422, content={"detail": str(exc)})
+
+
+@app.exception_handler(StorageError)
+async def _storage(_: Request, exc: StorageError) -> JSONResponse:
+    return JSONResponse(status_code=500, content={"detail": str(exc)})
+
+
+@app.get("/", tags=["meta"])
+def health() -> dict[str, str]:
+    return {"status": "ok", "version": __version__}
+
+
+for _module, _tag in (
+    (workspace, "workspaces"),
+    (project, "projects & subjects"),
+    (item, "items"),
+    (relation, "relations"),
+    (tag, "tags"),
+    (connection, "connections"),
+):
+    app.include_router(_module.router, prefix="/api", tags=[_tag])
+
+# UI estática (Alpine + ES modules, libs via CDN, sem build). Em /ui porque "/" já é o health check.
+_STATIC_DIR = Path(__file__).parent / "static"
+if _STATIC_DIR.is_dir():
+    app.mount("/ui", StaticFiles(directory=_STATIC_DIR, html=True), name="ui")
+

knowledge_os/api/routes/_common.py

@@ -0,0 +1,41 @@
+"""Peças comuns das rotas: o item de saída e a recusa de parâmetro de consulta desconhecido
+(ex.: um filtro do modelo antigo, como `scope` ou `status`, que agora são tags)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from fastapi import Request
+
+from knowledge_os.exceptions import ValidationError
+from knowledge_os.schemas.item_schemas import ItemResponse
+from knowledge_os.services.brain import Brain
+from knowledge_os.storage.files import ItemRecord
+
+
+def split(value: str | None) -> list[str] | None:
+    """`"a,b"` → `["a", "b"]` (None se vazio)."""
+    items = [v.strip() for v in (value or "").split(",") if v.strip()]
+    return items or None
+
+
+def check_query(request: Request, allowed: Iterable[str]) -> None:
+    """422 com os válidos se a consulta traz um parâmetro que a rota não conhece: sem isso um
+    filtro inexistente seria ignorado em silêncio e a lista pareceria filtrada."""
+    valid = sorted(set(allowed))
+    unknown = sorted(k for k in request.query_params if k not in valid)
+    if unknown:
+        raise ValidationError(
+            f"Parâmetro(s) desconhecido(s): {', '.join(unknown)}. Válidos: {', '.join(valid)}"
+        )
+
+
+def item_out(brain: Brain, record: ItemRecord) -> ItemResponse:
+    """O item completo da API a partir do registro."""
+    return ItemResponse.from_item(brain.view(record))
+
+
+def item_by_id(cid: str, item_id: str) -> ItemResponse:
+    """Lê de novo (snapshot atual) e devolve o item; NotFoundError se não existe."""
+    brain = Brain(cid)
+    return item_out(brain, brain.snapshot.require(item_id))

knowledge_os/api/routes/connection.py

@@ -0,0 +1,115 @@
+"""Rotas de connections sobre o connections.json: listar, ver, editar, testar, definir a
+padrão e apagar. Criar conexão é só pelo MCP (`connection_create`), nunca pela API."""
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Request, Response, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
+
+from knowledge_os.api.schemas.requests import ConnectionUpdate
+from knowledge_os.api.schemas.responses import (
+    ConnectionHealth,
+    ConnectionResponse,
+    ConnectionTestResponse,
+)
+from knowledge_os.exceptions import NotFoundError
+from knowledge_os.services.connection_service import Connection, ConnectionService
+
+
+class _SafeRoute(APIRoute):
+    """422 de validação sem o `input` recebido: o corpo pode trazer senha ou URL com senha."""
+
+    def get_route_handler(self) -> Callable[[Request], Any]:
+        original = super().get_route_handler()
+
+        async def handler(request: Request) -> Response:
+            try:
+                return await original(request)
+            except RequestValidationError as exc:
+                detail = [
+                    {"type": e["type"], "loc": list(e["loc"]), "msg": e["msg"]}
+                    for e in exc.errors()
+                ]
+                return JSONResponse(status_code=422, content={"detail": detail})
+
+        return handler
+
+
+router = APIRouter(route_class=_SafeRoute)
+
+
+def _folder_state(path: str | None) -> tuple[bool, bool]:
+    """(a pasta existe, é repositório git) — só para a UI mostrar o estado da conexão."""
+    if not path:
+        return False, False
+    folder = Path(path)
+    exists = folder.is_dir()
+    return exists, exists and (folder / ".git").exists()
+
+
+def _view(conn: Connection) -> dict[str, Any]:
+    """Serializa a conexão para a API: a pasta (repositório git), o estado dela e o remote."""
+    path = getattr(conn, "path", None)
+    path_exists, is_git_repo = _folder_state(path)
+    return {
+        "id": conn.id,
+        "name": conn.name,
+        "path": path,
+        "path_exists": path_exists,
+        "is_git_repo": is_git_repo,
+        "remote_url": getattr(conn, "remote_url", None),
+        "review_mode": getattr(conn, "review_mode", "direct"),
+        "enabled": bool(conn.is_active),
+        "is_default": bool(getattr(conn, "is_default", False)),
+        "last_test": getattr(conn, "last_test", None),
+        "created_at": conn.created_at,
+    }
+
+
+@router.get("/connections", response_model=list[ConnectionResponse])
+def list_connections():
+    return [_view(c) for c in ConnectionService().list()]
+
+
+# Antes de /connections/{id}, para "health" não ser lido como id.
+@router.get("/connections/health", response_model=list[ConnectionHealth])
+def connections_health():
+    """Cada conexão com o caminho da pasta, se é repositório git (`ok`) e os `.md` que a
+    leitura ignorou (`parse_errors`)."""
+    return ConnectionService().health()
+
+
+@router.get("/connections/{id}", response_model=ConnectionResponse)
+def get_connection(id: str):
+    return _view(ConnectionService().get(id))
+
+
+@router.patch("/connections/{id}", response_model=ConnectionResponse)
+def update_connection(id: str, req: ConnectionUpdate):
+    fields = req.model_dump(exclude_unset=True)
+    if "enabled" in fields:
+        fields["is_active"] = fields.pop("enabled")
+    if "name" in fields and fields["name"] is None:
+        del fields["name"]
+    return _view(ConnectionService().update(id, **fields))
+
+
+@router.delete("/connections/{id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_connection(id: str) -> Response:
+    if not ConnectionService().delete(id):
+        raise NotFoundError(f"Conexão não encontrada: {id}")
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post("/connections/{id}/test", response_model=ConnectionTestResponse)
+def test_connection(id: str):
+    return ConnectionService().test(id)
+
+
+@router.put("/connections/{id}/default", response_model=ConnectionResponse)
+def set_default_connection(id: str):
+    return _view(ConnectionService().set_default(id))

knowledge_os/api/routes/item.py

@@ -0,0 +1,236 @@
+"""Rotas de itens (v6): listar com filtros, ler, criar, atualizar, apagar, busca explicada,
+grafo do item e o valor de segredo.
+
+Toda validação de conteúdo é do `ItemService` (que usa `model.validate_entry`): campo
+desconhecido e valor fora da taxonomia voltam 422 com a mensagem do serviço, que lista os
+válidos. v6: sem subtype/scope/status/origin/ttl — a nuance e o ciclo vivem em `tags`, o
+alcance vem de onde o item mora.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response, status
+from fastapi.concurrency import run_in_threadpool
+
+from knowledge_os.api.deps import get_connection_id
+from knowledge_os.api.routes._common import (
+    check_query,
+    item_by_id,
+    item_out,
+    split,
+)
+from knowledge_os.api.schemas.requests import ItemCreate, ItemUpdate
+from knowledge_os.api.schemas.responses import ItemListResponse, ItemResponse
+from knowledge_os.exceptions import ValidationError
+from knowledge_os.model import TYPES
+from knowledge_os.services.brain import Brain
+from knowledge_os.services.graph import GraphService
+from knowledge_os.services.item_file import slugify
+from knowledge_os.services.item_service import MAX_LIMIT, ItemService
+from knowledge_os.services.secret_service import SecretService
+
+router = APIRouter()
+
+_LIST_PARAMS = ("workspace_id", "project_id", "subject_id", "type", "tag", "limit", "offset")
+_SEARCH_PARAMS = ("query", "workspace_id", "project_id", "subject_id", "types", "tags", "limit")
+_GRAPH_PARAMS = ("depth", "limit", "relation_types", "types", "direction")
+SEARCH_LIMIT = 50
+CSV = "um valor, ou vários separados por vírgula"
+
+
+def _choices(name: str, value: str | None, valid: tuple[str, ...]) -> set[str] | None:
+    values = split(value)
+    if values is None:
+        return None
+    bad = [v for v in values if v not in valid]
+    if bad:
+        raise ValidationError(f"{name} inválido: {', '.join(bad)}. Válidos: {', '.join(valid)}")
+    return set(values)
+
+
+def _require_place(cid: str, ws_id: str, pj_id: str | None, sj_id: str | None = None) -> None:
+    """A UI cria e move itens só para lugares que existem. Item pode morar no workspace (sem
+    project); nesse caso só o workspace é exigido."""
+    snap = Brain(cid).snapshot
+    ws = snap.workspace(ws_id)
+    if pj_id:
+        pj = snap.project(ws.id, pj_id)
+        if sj_id:
+            snap.subject(ws.id, pj.id, sj_id)
+
+
+@router.get("/items", response_model=ItemListResponse)
+def list_items(
+    request: Request,
+    workspace_id: str | None = None,
+    project_id: str | None = Query(default=None, description=CSV),
+    subject_id: str | None = Query(default=None, description=CSV),
+    type: str | None = Query(default=None, description=CSV),
+    tag: str | None = Query(default=None, description=f"{CSV}; o item precisa ter todas"),
+    limit: int = Query(default=100, ge=1, le=500),
+    offset: int = Query(default=0, ge=0),
+    cid: str = Depends(get_connection_id),
+):
+    """Itens da conexão (todos, inclusive os com a tag `archived`), mais antigos primeiro."""
+    check_query(request, _LIST_PARAMS)
+    types = _choices("type", type, tuple(TYPES))
+    tags = set(split(tag) or [])
+    projects, subjects = split(project_id), split(subject_id)
+    brain = Brain(cid)
+    snap = brain.snapshot
+
+    def wanted(r) -> bool:
+        return (
+            (not workspace_id or slugify(r.workspace or "") == workspace_id)
+            and (projects is None or slugify(r.project or "") in projects)
+            and (subjects is None or bool(r.subject and slugify(r.subject) in subjects))
+            and (types is None or r.type in types)
+            and tags <= set(r.tags or [])
+        )
+
+    records = sorted((r for r in snap.records.values() if wanted(r)),
+                     key=lambda r: (r.created_at, r.path))
+    page = records[offset:offset + limit]
+    return ItemListResponse(items=[item_out(brain, r) for r in page], total=len(records))
+
+
+@router.post("/items", status_code=status.HTTP_201_CREATED, response_model=ItemResponse)
+def create_item(req: ItemCreate, cid: str = Depends(get_connection_id)):
+    if req.sent("id"):
+        raise ValidationError("POST /api/items cria um item: não envie id (ele é gerado); para "
+                              "editar use PUT /api/items/{id}")
+    fields = req.service_fields()
+    ws = fields.pop("workspace")
+    pj = fields.pop("project", None)
+    sj = fields.pop("subject", None)
+    _require_place(cid, ws, pj, sj)
+    item = ItemService(cid).create(ws, pj, sj, **fields)
+    return item_by_id(cid, item.id)
+
+
+# Declarada antes de /items/{id} para "search" não ser lido como id.
+@router.get("/items/search")
+def search_items(
+    request: Request,
+    query: str = "",
+    workspace_id: str | None = Query(default=None, description="sem ele, todos os workspaces"),
+    project_id: str | None = Query(default=None, description=CSV),
+    subject_id: str | None = Query(default=None, description=CSV),
+    types: str | None = Query(default=None, description=CSV),
+    tags: str | None = Query(default=None, description=f"{CSV}; o item precisa ter todas"),
+    limit: int = Query(default=10, ge=1, le=SEARCH_LIMIT),
+    cid: str = Depends(get_connection_id),
+):
+    """A resposta do `ItemService.search` (`{results: [...]}`, sem `content`), com
+    `workspace_id`/`project_id`/`subject_id` em cada resultado para o link da UI.
+
+    Com `workspace_id`: o workspace inteiro; sem: tudo (`everywhere`). `project_id`/`subject_id`
+    restringem os resultados a esses lugares.
+    """
+    check_query(request, _SEARCH_PARAMS)
+    projects, subjects = split(project_id), split(subject_id)
+    narrowed = projects is not None or subjects is not None
+    service = ItemService(cid)
+    out = service.search(
+        query=query, workspace=workspace_id or None, everywhere=not workspace_id,
+        types=split(types), tags=split(tags),
+        # O serviço não filtra por project/subject: pede o máximo e corta aqui.
+        limit=MAX_LIMIT if narrowed else limit,
+    )
+    snap = Brain(cid).snapshot
+    results = []
+    for row in out.get("results", []):
+        record = snap.get(row["id"])
+        if record is None:
+            continue
+        pj = slugify(record.project or "") if record.project else None
+        sj = slugify(record.subject) if record.subject else None
+        if projects is not None and pj not in projects:
+            continue
+        if subjects is not None and sj not in subjects:
+            continue
+        results.append({**row, "workspace_id": slugify(record.workspace or ""),
+                        "project_id": pj, "subject_id": sj})
+    return {**out, "results": results[:limit]}
+
+
+@router.get("/items/{id}", response_model=ItemResponse)
+def get_item(id: str, cid: str = Depends(get_connection_id)):
+    # Sem somar `opened`: o sinal de uso mede o agente, não quem navega pela UI.
+    return item_by_id(cid, id)
+
+
+def _update(id: str, req: ItemUpdate, cid: str) -> ItemResponse:
+    record = Brain(cid).snapshot.require(id)
+    fields = req.service_fields()
+    if fields.get("workspace") or fields.get("project"):
+        _require_place(cid, fields.get("workspace") or slugify(record.workspace or ""),
+                       fields.get("project") or (slugify(record.project or "") or None),
+                       fields.get("subject"))
+    elif fields.get("subject"):
+        _require_place(cid, slugify(record.workspace or ""),
+                       slugify(record.project or "") or None, fields["subject"])
+    ItemService(cid).update(id, **fields)
+    return item_by_id(cid, id)
+
+
+@router.put("/items/{id}", response_model=ItemResponse)
+def update_item(id: str, req: ItemUpdate, cid: str = Depends(get_connection_id)):
+    """Atualização parcial (igual ao PATCH): só os campos enviados mudam."""
+    return _update(id, req, cid)
+
+
+@router.patch("/items/{id}", response_model=ItemResponse)
+def patch_item(id: str, req: ItemUpdate, cid: str = Depends(get_connection_id)):
+    return _update(id, req, cid)
+
+
+@router.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_item(id: str, cid: str = Depends(get_connection_id)) -> Response:
+    """Apaga o item e as relações que apontam para ele, num commit."""
+    ItemService(cid).remove(id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.get("/items/{id}/graph")
+def item_graph(
+    request: Request,
+    id: str,
+    depth: int = 1,
+    limit: int = 20,
+    relation_types: str | None = Query(default=None, description=CSV),
+    types: str | None = Query(default=None, description=CSV),
+    direction: str = "both",
+    cid: str = Depends(get_connection_id),
+):
+    """O `item_graph` a partir do item: `{nodes: [{key, id, type, title, summary, hop}],
+    edges: [{from, type, to}], truncated, total_by_hop}` (`from`/`to` = key, ou id quando o
+    item não tem key)."""
+    check_query(request, _GRAPH_PARAMS)
+    Brain(cid).snapshot.require(id)
+    return GraphService(cid).graph(
+        [id], depth=depth, limit=limit,
+        relation_types=split(relation_types), types=split(types), direction=direction,
+    )
+
+
+# Valor de segredo: entra só por aqui (o formulário da UI) e nenhuma rota o devolve. O corpo é
+# lido à mão para que um erro de validação nunca ecoe o valor (o 422 padrão traz o `input`).
+@router.put("/items/{id}/secret", status_code=status.HTTP_204_NO_CONTENT)
+async def set_secret_value(
+    id: str, request: Request, cid: str = Depends(get_connection_id)
+) -> Response:
+    try:
+        body = await request.json()
+    except ValueError:
+        raise HTTPException(422, 'Corpo deve ser JSON: {"value": "..."}') from None
+    value = body.get("value") if isinstance(body, dict) else None
+    if not isinstance(value, str) or not value:
+        raise HTTPException(422, "Informe value (texto não vazio)")
+    # keyring e escrita em disco bloqueiam: fora do event loop da UI
+    await run_in_threadpool(SecretService(cid).set_value, id, value)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.delete("/items/{id}/secret", status_code=status.HTTP_204_NO_CONTENT)
+def clear_secret_value(id: str, cid: str = Depends(get_connection_id)) -> Response:
+    SecretService(cid).clear_value(id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

knowledge_os/api/routes/project.py

@@ -0,0 +1,128 @@
+"""Rotas de projects e subjects (v2; id = slug do nome, único dentro do pai).
+
+Nas rotas por id, `workspace_id` (query) desfaz a ambiguidade quando o mesmo project existe em
+mais de um workspace (ex.: `geral`). As listas vêm de `ProjectService.rows()` /
+`SubjectService.rows()` (com `scope` efetivo e explícito) e indicam de onde vem o herdado.
+"""
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, Response, status
+
+from knowledge_os.api.deps import get_connection_id
+from knowledge_os.api.schemas.requests import (
+    ProjectCreate,
+    ProjectUpdate,
+    SubjectCreate,
+    SubjectUpdate,
+)
+from knowledge_os.api.schemas.responses import ProjectRow, SubjectRow
+from knowledge_os.exceptions import NotFoundError
+from knowledge_os.services.brain import Brain
+from knowledge_os.services.project_service import ProjectService
+from knowledge_os.services.subject_service import SubjectService
+
+router = APIRouter()
+
+
+def _project_rows(cid: str, ws_id: str) -> list[dict[str, Any]]:
+    ws = Brain(cid).snapshot.workspace(ws_id)
+    return list(ProjectService(cid).rows(ws.id))
+
+
+def _project_row(cid: str, ws_id: str, pj_id: str) -> dict[str, Any]:
+    for row in _project_rows(cid, ws_id):
+        if row["id"] == pj_id:
+            return row
+    raise NotFoundError(f"Project não encontrado: {pj_id}")
+
+
+def _subject_rows(cid: str, ws_id: str, pj_id: str) -> list[dict[str, Any]]:
+    snap = Brain(cid).snapshot
+    ws = snap.workspace(ws_id)
+    pj = snap.project(ws.id, pj_id)
+    return [{**row, "workspace_id": ws.id, "project_id": pj.id}
+            for row in SubjectService(cid).rows(ws.id, pj.id)]
+
+
+def _subject_row(cid: str, ws_id: str, pj_id: str, sj_id: str) -> dict[str, Any]:
+    for row in _subject_rows(cid, ws_id, pj_id):
+        if row["id"] == sj_id:
+            return row
+    raise NotFoundError(f"Subject não encontrado: {sj_id}")
+
+
+# ---------------------------------------------------------------------------- projects
+
+
+@router.get("/projects", response_model=list[ProjectRow])
+def list_projects(workspace_id: str | None = None, cid: str = Depends(get_connection_id)):
+    if workspace_id:
+        return _project_rows(cid, workspace_id)
+    return [row for ws in Brain(cid).snapshot.workspaces() for row in _project_rows(cid, ws.id)]
+
+
+@router.post("/projects", status_code=status.HTTP_201_CREATED, response_model=ProjectRow)
+def create_project(req: ProjectCreate, cid: str = Depends(get_connection_id)):
+    pj = ProjectService(cid).create(req.workspace_id, req.name, req.description)
+    return _project_row(cid, pj.workspace_id, pj.id)
+
+
+@router.get("/projects/{id}", response_model=ProjectRow)
+def get_project(id: str, workspace_id: str | None = None, cid: str = Depends(get_connection_id)):
+    pj = ProjectService(cid).find_by_id(id, workspace_id)
+    return _project_row(cid, pj.workspace_id, pj.id)
+
+
+@router.put("/projects/{id}", response_model=ProjectRow)
+def update_project(
+    id: str, req: ProjectUpdate, workspace_id: str | None = None,
+    cid: str = Depends(get_connection_id),
+):
+    """Só o que vier muda: `name` renomeia, `description` atualiza."""
+    svc = ProjectService(cid)
+    pj = svc.find_by_id(id, workspace_id)
+    updated = svc.update(pj.workspace_id, pj.id, req.name, req.description)
+    return _project_row(cid, updated.workspace_id, updated.id)
+
+
+@router.delete("/projects/{id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_project(
+    id: str, workspace_id: str | None = None, cid: str = Depends(get_connection_id)
+) -> Response:
+    svc = ProjectService(cid)
+    pj = svc.find_by_id(id, workspace_id)
+    svc.delete(pj.workspace_id, pj.id)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ---------------------------------------------------------------------------- subjects
+
+
+@router.get("/subjects", response_model=list[SubjectRow])
+def list_subjects(workspace_id: str, project_id: str, cid: str = Depends(get_connection_id)):
+    return _subject_rows(cid, workspace_id, project_id)
+
+
+@router.post("/subjects", status_code=status.HTTP_201_CREATED, response_model=SubjectRow)
+def create_subject(req: SubjectCreate, cid: str = Depends(get_connection_id)):
+    sj = SubjectService(cid).create(req.workspace_id, req.project_id, req.name,
+                                    req.description)
+    return _subject_row(cid, sj.workspace_id, sj.project_id, sj.id)
+
+
+@router.put("/subjects/{id}", response_model=SubjectRow)
+def update_subject(id: str, req: SubjectUpdate, workspace_id: str, project_id: str,
+                   cid: str = Depends(get_connection_id)):
+    """Só o que vier muda: `name` renomeia, `description` atualiza."""
+    sj = SubjectService(cid).update(workspace_id, project_id, id, req.name, req.description)
+    return _subject_row(cid, sj.workspace_id, sj.project_id, sj.id)
+
+
+@router.delete("/subjects/{id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_subject(id: str, workspace_id: str, project_id: str,
+                   cid: str = Depends(get_connection_id)) -> Response:
+    """Os itens do subject ficam no project, sem subject."""
+    if not SubjectService(cid).delete(workspace_id, project_id, id):
+        raise NotFoundError(f"Subject não encontrado: {id}")
+    return Response(status_code=status.HTTP_204_NO_CONTENT)

knowledge_os/api/routes/relation.py

@@ -0,0 +1,24 @@
+"""Rotas de relações (v2): criar e apagar em lote pelo `RelationService` (`{source, type,
+target}`, key ou id, atômico). Ler é pelo grafo (`GET /items/{id}/graph`)."""
+
+from fastapi import APIRouter, Depends, status
+
+from knowledge_os.api.deps import get_connection_id
+from knowledge_os.api.schemas.requests import RelationBatch
+from knowledge_os.api.schemas.responses import RelationRow
+from knowledge_os.services.relation_service import RelationService
+
+router = APIRouter()
+
+
+@router.post("/relations", status_code=status.HTTP_201_CREATED,
+             response_model=list[RelationRow], response_model_exclude_none=True)
+def create_relations(req: RelationBatch, cid: str = Depends(get_connection_id)):
+    """`created` ou `unchanged` (já existia) por entrada; `supersedes` arquiva o alvo."""
+    return RelationService(cid).create(req.items)
+
+
+@router.delete("/relations", response_model=list[RelationRow], response_model_exclude_none=True)
+def delete_relations(req: RelationBatch, cid: str = Depends(get_connection_id)):
+    """`deleted` ou `missing` por entrada."""
+    return RelationService(cid).delete(req.items)