Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

refactor(server): split schemas.py into a schemas/ package (#246)

Raghav Chamadiya09dccaaaf325
diff --git a/packages/server/src/repowise/server/schemas.py b/packages/server/src/repowise/server/schemas.py
deleted file mode 100644
index e91a7cc04..000000000
--- a/packages/server/src/repowise/server/schemas.py
+++ /dev/null
@@ -1,1567 +0,0 @@
-"""Pydantic request/response models for the repowise REST API."""
-
-from __future__ import annotations
-
-import json
-from datetime import datetime
-from pathlib import Path
-from typing import Generic, TypeVar
-
-from pydantic import BaseModel, Field, field_validator
-
-# ---------------------------------------------------------------------------
-# Pagination envelope — shared across list endpoints (git, symbols, etc.)
-# ---------------------------------------------------------------------------
-
-T = TypeVar("T")
-
-
-class Paginated(BaseModel, Generic[T]):
- """Stable envelope for paginated list endpoints.
-
- Lets the UI show "Showing N of M / Load more" without guessing whether
- a list was truncated by the server. `next_offset` is null when there
- are no further pages.
- """
-
- items: list[T]
- total: int
- has_more: bool
- next_offset: int | None = None
-
-
-# ---------------------------------------------------------------------------
-# Repository
-# ---------------------------------------------------------------------------
-
-
-class RepoCreate(BaseModel):
- name: str
- local_path: str
- url: str = ""
- default_branch: str = "main"
- settings: dict | None = None
-
- @field_validator("local_path")
- @classmethod
- def validate_local_path(cls, v: str) -> str:
- resolved = Path(v).resolve()
- if ".." in Path(v).parts:
- raise ValueError("local_path must not contain '..' segments")
- if not resolved.is_dir():
- raise ValueError(f"local_path does not exist or is not a directory: {resolved}")
- if not (resolved / ".git").exists():
- raise ValueError(f"local_path is not a git repository (no .git found): {resolved}")
- return str(resolved)
-
-
-class RepoUpdate(BaseModel):
- name: str | None = None
- url: str | None = None
- default_branch: str | None = None
- settings: dict | None = None
-
-
-class RepoResponse(BaseModel):
- id: str
- name: str
- url: str
- local_path: str
- default_branch: str
- head_commit: str | None
- settings: dict
- created_at: datetime
- updated_at: datetime
- # Workspace context — populated when the server is running in
- # workspace mode. ``status`` indicates whether the repo has been
- # indexed yet; the web UI uses it to render "needs index" CTA cards
- # instead of silently dropping unindexed workspace repos from the
- # sidebar. Always ``None`` in single-repo mode.
- workspace_alias: str | None = None
- workspace_status: str | None = None
- is_primary: bool | None = None
- docs_enabled: bool | None = None
- docs_skip_reason: str | None = None
-
- @classmethod
- def from_orm(cls, obj: object) -> RepoResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- name=obj.name, # type: ignore[attr-defined]
- url=obj.url, # type: ignore[attr-defined]
- local_path=obj.local_path, # type: ignore[attr-defined]
- default_branch=obj.default_branch, # type: ignore[attr-defined]
- head_commit=obj.head_commit, # type: ignore[attr-defined]
- settings=json.loads(obj.settings_json), # type: ignore[attr-defined]
- created_at=obj.created_at, # type: ignore[attr-defined]
- updated_at=obj.updated_at, # type: ignore[attr-defined]
- )
-
-
-# ---------------------------------------------------------------------------
-# Pages
-# ---------------------------------------------------------------------------
-
-
-class PageResponse(BaseModel):
- id: str
- repository_id: str
- page_type: str
- title: str
- content: str
- target_path: str
- source_hash: str
- model_name: str
- provider_name: str
- input_tokens: int
- output_tokens: int
- cached_tokens: int
- generation_level: int
- version: int
- confidence: float
- freshness_status: str
- metadata: dict
- human_notes: str | None = None
- created_at: datetime
- updated_at: datetime
-
- @classmethod
- def from_orm(cls, obj: object) -> PageResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- repository_id=obj.repository_id, # type: ignore[attr-defined]
- page_type=obj.page_type, # type: ignore[attr-defined]
- title=obj.title, # type: ignore[attr-defined]
- content=obj.content, # type: ignore[attr-defined]
- target_path=obj.target_path, # type: ignore[attr-defined]
- source_hash=obj.source_hash, # type: ignore[attr-defined]
- model_name=obj.model_name, # type: ignore[attr-defined]
- provider_name=obj.provider_name, # type: ignore[attr-defined]
- input_tokens=obj.input_tokens, # type: ignore[attr-defined]
- output_tokens=obj.output_tokens, # type: ignore[attr-defined]
- cached_tokens=obj.cached_tokens, # type: ignore[attr-defined]
- generation_level=obj.generation_level, # type: ignore[attr-defined]
- version=obj.version, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
- freshness_status=obj.freshness_status, # type: ignore[attr-defined]
- metadata=json.loads(obj.metadata_json), # type: ignore[attr-defined]
- human_notes=obj.human_notes, # type: ignore[attr-defined]
- created_at=obj.created_at, # type: ignore[attr-defined]
- updated_at=obj.updated_at, # type: ignore[attr-defined]
- )
-
-
-class PageVersionResponse(BaseModel):
- id: str
- page_id: str
- version: int
- page_type: str
- title: str
- content: str
- source_hash: str
- model_name: str
- provider_name: str
- input_tokens: int
- output_tokens: int
- confidence: float
- archived_at: datetime
-
- @classmethod
- def from_orm(cls, obj: object) -> PageVersionResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- page_id=obj.page_id, # type: ignore[attr-defined]
- version=obj.version, # type: ignore[attr-defined]
- page_type=obj.page_type, # type: ignore[attr-defined]
- title=obj.title, # type: ignore[attr-defined]
- content=obj.content, # type: ignore[attr-defined]
- source_hash=obj.source_hash, # type: ignore[attr-defined]
- model_name=obj.model_name, # type: ignore[attr-defined]
- provider_name=obj.provider_name, # type: ignore[attr-defined]
- input_tokens=obj.input_tokens, # type: ignore[attr-defined]
- output_tokens=obj.output_tokens, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
- archived_at=obj.archived_at, # type: ignore[attr-defined]
- )
-
-
-# ---------------------------------------------------------------------------
-# Jobs
-# ---------------------------------------------------------------------------
-
-
-class JobResponse(BaseModel):
- id: str
- repository_id: str
- status: str
- provider_name: str
- model_name: str
- total_pages: int
- completed_pages: int
- failed_pages: int
- current_level: int
- error_message: str | None
- config: dict
- created_at: datetime
- updated_at: datetime
- started_at: datetime | None
- finished_at: datetime | None
-
- @classmethod
- def from_orm(cls, obj: object) -> JobResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- repository_id=obj.repository_id, # type: ignore[attr-defined]
- status=obj.status, # type: ignore[attr-defined]
- provider_name=obj.provider_name, # type: ignore[attr-defined]
- model_name=obj.model_name, # type: ignore[attr-defined]
- total_pages=obj.total_pages, # type: ignore[attr-defined]
- completed_pages=obj.completed_pages, # type: ignore[attr-defined]
- failed_pages=obj.failed_pages, # type: ignore[attr-defined]
- current_level=obj.current_level, # type: ignore[attr-defined]
- error_message=obj.error_message, # type: ignore[attr-defined]
- config=json.loads(obj.config_json), # type: ignore[attr-defined]
- created_at=obj.created_at, # type: ignore[attr-defined]
- updated_at=obj.updated_at, # type: ignore[attr-defined]
- started_at=obj.started_at, # type: ignore[attr-defined]
- finished_at=obj.finished_at, # type: ignore[attr-defined]
- )
-
-
-# ---------------------------------------------------------------------------
-# Search
-# ---------------------------------------------------------------------------
-
-
-class SearchRequest(BaseModel):
- query: str
- search_type: str = "semantic"
- limit: int = Field(default=10, ge=1, le=100)
-
-
-class SearchResultResponse(BaseModel):
- page_id: str
- title: str
- page_type: str
- target_path: str
- score: float
- snippet: str
- search_type: str
-
-
-# ---------------------------------------------------------------------------
-# Symbols
-# ---------------------------------------------------------------------------
-
-
-class SymbolImportanceComponents(BaseModel):
- """Transparent breakdown of the composite importance score so the UI can
- explain *why* a symbol ranks where it does. All fields are normalized to
- [0, 1] except booleans."""
-
- file_pagerank: float = 0.0
- visibility_factor: float = 0.5
- complexity_norm: float = 0.0
- kind_boost: float = 1.0
- is_entry_point: bool = False
-
-
-class SymbolResponse(BaseModel):
- id: str
- repository_id: str
- file_path: str
- symbol_id: str
- name: str
- qualified_name: str
- kind: str
- signature: str
- start_line: int
- end_line: int
- docstring: str | None
- visibility: str
- is_async: bool
- complexity_estimate: int
- language: str
- parent_name: str | None
- # Importance signals (populated when the list endpoint joins GraphNode /
- # GitMetadata; nullable so single-symbol lookups remain lightweight).
- importance_score: float | None = None
- importance_components: SymbolImportanceComponents | None = None
- file_pagerank: float | None = None
- is_entry_point: bool | None = None
- file_churn_percentile: float | None = None
- file_is_hotspot: bool | None = None
-
- @classmethod
- def from_orm(cls, obj: object) -> SymbolResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- repository_id=obj.repository_id, # type: ignore[attr-defined]
- file_path=obj.file_path, # type: ignore[attr-defined]
- symbol_id=obj.symbol_id, # type: ignore[attr-defined]
- name=obj.name, # type: ignore[attr-defined]
- qualified_name=obj.qualified_name, # type: ignore[attr-defined]
- kind=obj.kind, # type: ignore[attr-defined]
- signature=obj.signature, # type: ignore[attr-defined]
- start_line=obj.start_line, # type: ignore[attr-defined]
- end_line=obj.end_line, # type: ignore[attr-defined]
- docstring=obj.docstring, # type: ignore[attr-defined]
- visibility=obj.visibility, # type: ignore[attr-defined]
- is_async=obj.is_async, # type: ignore[attr-defined]
- complexity_estimate=obj.complexity_estimate, # type: ignore[attr-defined]
- language=obj.language, # type: ignore[attr-defined]
- parent_name=obj.parent_name, # type: ignore[attr-defined]
- )
-
-
-# ---------------------------------------------------------------------------
-# Graph
-# ---------------------------------------------------------------------------
-
-
-class GraphNodeResponse(BaseModel):
- node_id: str
- node_type: str
- language: str
- symbol_count: int
- pagerank: float
- betweenness: float
- community_id: int
- is_test: bool = False
- is_entry_point: bool = False
- has_doc: bool = False
- # Cross-link signals (populated by _collect_node_signals)
- is_hotspot: bool = False
- churn_percentile: float | None = None
- is_dead: bool = False
- dead_confidence: float | None = None
- has_decision: bool = False
- primary_owner: str | None = None
-
-
-class GraphEdgeResponse(BaseModel):
- source: str
- target: str
- imported_names: list[str]
-
-
-class GraphExportResponse(BaseModel):
- nodes: list[GraphNodeResponse]
- links: list[GraphEdgeResponse]
- # When the graph is too large to return in full, the server caps the response
- # to top-N nodes by PageRank. Clients should surface a banner.
- truncated: bool = False
- total_node_count: int | None = None
-
-
-# Architecture / community super-node graph
-class ArchitectureNodeResponse(BaseModel):
- community_id: int
- label: str
- cohesion: float
- member_count: int
- top_file: str
- avg_pagerank: float
- hotspot_count: int = 0
- dead_count: int = 0
- has_decision: bool = False
- doc_coverage_pct: float = 0.0
- languages: list[str] = []
-
-
-class ArchitectureEdgeResponse(BaseModel):
- source: int
- target: int
- edge_count: int
-
-
-class ArchitectureGraphResponse(BaseModel):
- nodes: list[ArchitectureNodeResponse]
- edges: list[ArchitectureEdgeResponse]
-
-
-# ---------------------------------------------------------------------------
-# Webhooks
-# ---------------------------------------------------------------------------
-
-
-class WebhookResponse(BaseModel):
- event_id: str
- status: str = "accepted"
-
-
-# ---------------------------------------------------------------------------
-# Git Intelligence
-# ---------------------------------------------------------------------------
-
-
-class GitMetadataResponse(BaseModel):
- file_path: str
- commit_count_total: int
- commit_count_90d: int
- commit_count_30d: int
- first_commit_at: datetime | None
- last_commit_at: datetime | None
- primary_owner_name: str | None
- primary_owner_email: str | None
- primary_owner_commit_pct: float | None
- recent_owner_name: str | None
- recent_owner_commit_pct: float | None
- top_authors: list[dict]
- significant_commits: list[dict]
- co_change_partners: list[dict]
- is_hotspot: bool
- is_stable: bool
- churn_percentile: float
- age_days: int
- bus_factor: int
- contributor_count: int
- lines_added_90d: int
- lines_deleted_90d: int
- avg_commit_size: float
- commit_categories: dict
- merge_commit_count_90d: int
- test_gap: bool | None = None
-
- @classmethod
- def from_orm(cls, obj: object) -> GitMetadataResponse:
- return cls(
- file_path=obj.file_path, # type: ignore[attr-defined]
- commit_count_total=obj.commit_count_total, # type: ignore[attr-defined]
- commit_count_90d=obj.commit_count_90d, # type: ignore[attr-defined]
- commit_count_30d=obj.commit_count_30d, # type: ignore[attr-defined]
- first_commit_at=obj.first_commit_at, # type: ignore[attr-defined]
- last_commit_at=obj.last_commit_at, # type: ignore[attr-defined]
- primary_owner_name=obj.primary_owner_name, # type: ignore[attr-defined]
- primary_owner_email=obj.primary_owner_email, # type: ignore[attr-defined]
- primary_owner_commit_pct=obj.primary_owner_commit_pct, # type: ignore[attr-defined]
- recent_owner_name=obj.recent_owner_name, # type: ignore[attr-defined]
- recent_owner_commit_pct=obj.recent_owner_commit_pct, # type: ignore[attr-defined]
- top_authors=json.loads(obj.top_authors_json), # type: ignore[attr-defined]
- significant_commits=json.loads(obj.significant_commits_json), # type: ignore[attr-defined]
- co_change_partners=json.loads(obj.co_change_partners_json), # type: ignore[attr-defined]
- is_hotspot=obj.is_hotspot, # type: ignore[attr-defined]
- is_stable=obj.is_stable, # type: ignore[attr-defined]
- # Normalize 0–1 → 0–100 to match the rest of the HTTP API.
- churn_percentile=(obj.churn_percentile or 0.0) * 100.0, # type: ignore[attr-defined]
- age_days=obj.age_days, # type: ignore[attr-defined]
- bus_factor=obj.bus_factor or 0, # type: ignore[attr-defined]
- contributor_count=obj.contributor_count or 0, # type: ignore[attr-defined]
- lines_added_90d=obj.lines_added_90d or 0, # type: ignore[attr-defined]
- lines_deleted_90d=obj.lines_deleted_90d or 0, # type: ignore[attr-defined]
- avg_commit_size=obj.avg_commit_size or 0.0, # type: ignore[attr-defined]
- commit_categories=json.loads(obj.commit_categories_json)
- if obj.commit_categories_json
- else {}, # type: ignore[attr-defined]
- merge_commit_count_90d=obj.merge_commit_count_90d or 0, # type: ignore[attr-defined]
- )
-
-
-class HotspotResponse(BaseModel):
- file_path: str
- commit_count_total: int = 0
- commit_count_90d: int
- commit_count_30d: int
- churn_percentile: float
- temporal_hotspot_score: float | None = None
- primary_owner: str | None
- primary_owner_commit_pct: float | None = None
- recent_owner_name: str | None = None
- recent_owner_commit_pct: float | None = None
- is_hotspot: bool
- is_stable: bool
- bus_factor: int
- contributor_count: int
- lines_added_90d: int
- lines_deleted_90d: int
- avg_commit_size: float
- commit_categories: dict
- merge_commit_count_90d: int = 0
- commit_count_capped: bool = False
- age_days: int = 0
- last_commit_at: datetime | None = None
-
-
-class OwnershipEntry(BaseModel):
- module_path: str
- primary_owner: str | None
- owner_pct: float | None
- file_count: int
- is_silo: bool
-
-
-class GitSummaryResponse(BaseModel):
- total_files: int
- hotspot_count: int
- stable_count: int
- average_churn_percentile: float
- top_owners: list[dict]
-
-
-# ---------------------------------------------------------------------------
-# Dead Code
-# ---------------------------------------------------------------------------
-
-
-class DeadCodeFindingResponse(BaseModel):
- id: str
- kind: str
- file_path: str
- symbol_name: str | None
- symbol_kind: str | None
- confidence: float
- reason: str
- lines: int
- safe_to_delete: bool
- primary_owner: str | None
- status: str
- note: str | None
-
- @classmethod
- def from_orm(cls, obj: object) -> DeadCodeFindingResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- kind=obj.kind, # type: ignore[attr-defined]
- file_path=obj.file_path, # type: ignore[attr-defined]
- symbol_name=obj.symbol_name, # type: ignore[attr-defined]
- symbol_kind=obj.symbol_kind, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
- reason=obj.reason, # type: ignore[attr-defined]
- lines=obj.lines, # type: ignore[attr-defined]
- safe_to_delete=obj.safe_to_delete, # type: ignore[attr-defined]
- primary_owner=obj.primary_owner, # type: ignore[attr-defined]
- status=obj.status, # type: ignore[attr-defined]
- note=obj.note, # type: ignore[attr-defined]
- )
-
-
-class DeadCodePatchRequest(BaseModel):
- status: str
- note: str | None = None
-
-
-class DeadCodeSummaryResponse(BaseModel):
- total_findings: int
- confidence_summary: dict
- deletable_lines: int
- total_lines: int
- by_kind: dict
-
-
-# ---------------------------------------------------------------------------
-# Security
-# ---------------------------------------------------------------------------
-
-
-class SecurityFindingResponse(BaseModel):
- id: int
- file_path: str
- kind: str
- severity: str
- snippet: str | None
- detected_at: datetime
-
-
-# ---------------------------------------------------------------------------
-# Repo Stats
-# ---------------------------------------------------------------------------
-
-
-class RepoStatsResponse(BaseModel):
- file_count: int
- symbol_count: int
- entry_point_count: int
- doc_coverage_pct: float
- freshness_score: float
- dead_export_count: int
-
-
-# ---------------------------------------------------------------------------
-# Module Graph
-# ---------------------------------------------------------------------------
-
-
-class ModuleNodeResponse(BaseModel):
- module_id: str
- file_count: int
- symbol_count: int
- avg_pagerank: float
- doc_coverage_pct: float
- hotspot_count: int = 0
- dead_count: int = 0
- has_decision: bool = False
- primary_owner: str | None = None
-
-
-class ModuleEdgeResponse(BaseModel):
- source: str
- target: str
- edge_count: int
-
-
-class ModuleGraphResponse(BaseModel):
- nodes: list[ModuleNodeResponse]
- edges: list[ModuleEdgeResponse]
-
-
-# ---------------------------------------------------------------------------
-# Ego Graph
-# ---------------------------------------------------------------------------
-
-
-class EgoGraphResponse(BaseModel):
- nodes: list[GraphNodeResponse]
- links: list[GraphEdgeResponse]
- center_node_id: str
- center_git_meta: GitMetadataResponse | None
- inbound_count: int
- outbound_count: int
-
-
-class NodeSearchResult(BaseModel):
- node_id: str
- language: str
- symbol_count: int
-
-
-# ---------------------------------------------------------------------------
-# Dead Code Graph
-# ---------------------------------------------------------------------------
-
-
-class DeadCodeGraphNodeResponse(BaseModel):
- node_id: str
- node_type: str
- language: str
- symbol_count: int
- pagerank: float
- betweenness: float
- community_id: int
- is_test: bool = False
- is_entry_point: bool = False
- has_doc: bool = False
- is_hotspot: bool = False
- churn_percentile: float | None = None
- is_dead: bool = False
- dead_confidence: float | None = None
- has_decision: bool = False
- primary_owner: str | None = None
- confidence_group: str # "certain" | "likely" | "neighbor"
-
-
-class DeadCodeGraphResponse(BaseModel):
- nodes: list[DeadCodeGraphNodeResponse]
- links: list[GraphEdgeResponse]
-
-
-# ---------------------------------------------------------------------------
-# Hot Files Graph
-# ---------------------------------------------------------------------------
-
-
-class HotFilesNodeResponse(BaseModel):
- node_id: str
- node_type: str
- language: str
- symbol_count: int
- pagerank: float
- betweenness: float
- community_id: int
- is_test: bool = False
- is_entry_point: bool = False
- has_doc: bool = False
- is_hotspot: bool = False
- churn_percentile: float | None = None
- is_dead: bool = False
- dead_confidence: float | None = None
- has_decision: bool = False
- primary_owner: str | None = None
- commit_count: int
-
-
-class HotFilesGraphResponse(BaseModel):
- nodes: list[HotFilesNodeResponse]
- links: list[GraphEdgeResponse]
-
-
-# ---------------------------------------------------------------------------
-# Graph Intelligence
-# ---------------------------------------------------------------------------
-
-
-class SymbolNodeSummary(BaseModel):
- symbol_id: str
- name: str
- kind: str
- file: str
- start_line: int | None = None
- signature: str | None = None
-
-
-class CallerCalleeEntry(BaseModel):
- symbol_id: str
- name: str
- kind: str
- file: str
- start_line: int | None = None
- edge_type: str
- confidence: float
-
-
-class CallersCalleesResponse(BaseModel):
- symbol_id: str
- symbol: SymbolNodeSummary
- callers: list[CallerCalleeEntry]
- callees: list[CallerCalleeEntry]
- caller_count: int
- callee_count: int
- truncated: bool
-
-
-class CommunityMember(BaseModel):
- path: str
- pagerank: float
- is_entry_point: bool
-
-
-class NeighboringCommunity(BaseModel):
- community_id: int
- label: str
- cross_edge_count: int
-
-
-class CommunityDetailResponse(BaseModel):
- community_id: int
- label: str
- cohesion: float
- member_count: int
- members: list[CommunityMember]
- truncated: bool
- neighboring_communities: list[NeighboringCommunity]
-
-
-class CommunitySummaryItem(BaseModel):
- community_id: int
- label: str
- cohesion: float
- member_count: int
- top_file: str
-
-
-class GraphMetricsResponse(BaseModel):
- target: str
- node_type: str
- pagerank: float
- pagerank_percentile: int
- betweenness: float
- betweenness_percentile: int
- community_id: int
- community_label: str | None
- is_entry_point: bool
- in_degree: int
- out_degree: int
- entry_point_score: float | None = None
- kind: str | None = None
- file: str | None = None
-
-
-class ExecutionFlowEntry(BaseModel):
- entry_point: str
- entry_point_name: str
- entry_point_score: float
- trace: list[str]
- depth: int
- crosses_community: bool
- communities_visited: list[int]
-
-
-class ExecutionFlowsResponse(BaseModel):
- total_entry_points: int
- flows: list[ExecutionFlowEntry]
-
-
-# ---------------------------------------------------------------------------
-# Blast Radius
-# ---------------------------------------------------------------------------
-
-
-class BlastRadiusRequest(BaseModel):
- changed_files: list[str]
- max_depth: int = Field(default=3, ge=1, le=10)
-
-
-class DirectRiskEntry(BaseModel):
- path: str
- risk_score: float
- temporal_hotspot: float
- centrality: float
-
-
-class TransitiveEntry(BaseModel):
- path: str
- depth: int
-
-
-class CochangeWarning(BaseModel):
- changed: str
- missing_partner: str
- score: float
-
-
-class ReviewerEntry(BaseModel):
- email: str
- files: int
- ownership_pct: float
-
-
-class BlastRadiusResponse(BaseModel):
- direct_risks: list[DirectRiskEntry]
- transitive_affected: list[TransitiveEntry]
- cochange_warnings: list[CochangeWarning]
- recommended_reviewers: list[ReviewerEntry]
- test_gaps: list[str]
- overall_risk_score: float
-
-
-# ---------------------------------------------------------------------------
-# Health
-# ---------------------------------------------------------------------------
-
-
-class HealthResponse(BaseModel):
- status: str
- db: str
- version: str
-
-
-class CoordinatorHealthResponse(BaseModel):
- sql_pages: int | None
- vector_count: int | None
- graph_nodes: int | None
- drift_pct: float | None
- status: str # "ok" | "warning" | "critical"
-
-
-# ---------------------------------------------------------------------------
-# Knowledge Map
-# ---------------------------------------------------------------------------
-
-
-class KnowledgeMapOwner(BaseModel):
- email: str
- name: str
- files_owned: int
- percentage: float
-
-
-class KnowledgeMapSilo(BaseModel):
- file_path: str
- owner_email: str
- owner_pct: float
-
-
-class KnowledgeMapTarget(BaseModel):
- path: str
- pagerank: float
- doc_words: int
-
-
-class KnowledgeMapResponse(BaseModel):
- top_owners: list[KnowledgeMapOwner]
- knowledge_silos: list[KnowledgeMapSilo]
- onboarding_targets: list[KnowledgeMapTarget]
-
-
-# ---------------------------------------------------------------------------
-# Decisions
-# ---------------------------------------------------------------------------
-
-
-class DecisionRecordResponse(BaseModel):
- id: str
- repository_id: str
- title: str
- status: str
- context: str
- decision: str
- rationale: str
- alternatives: list[str]
- consequences: list[str]
- affected_files: list[str]
- affected_modules: list[str]
- tags: list[str]
- source: str
- evidence_commits: list[str]
- evidence_file: str | None
- evidence_line: int | None
- confidence: float
- staleness_score: float
- verification: str = "unverified"
- superseded_by: str | None
- last_code_change: datetime | None
- created_at: datetime
- updated_at: datetime
-
- @classmethod
- def from_orm(cls, obj: object) -> DecisionRecordResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- repository_id=obj.repository_id, # type: ignore[attr-defined]
- title=obj.title, # type: ignore[attr-defined]
- status=obj.status, # type: ignore[attr-defined]
- context=obj.context, # type: ignore[attr-defined]
- decision=obj.decision, # type: ignore[attr-defined]
- rationale=obj.rationale, # type: ignore[attr-defined]
- alternatives=json.loads(obj.alternatives_json), # type: ignore[attr-defined]
- consequences=json.loads(obj.consequences_json), # type: ignore[attr-defined]
- affected_files=json.loads(obj.affected_files_json), # type: ignore[attr-defined]
- affected_modules=json.loads(obj.affected_modules_json), # type: ignore[attr-defined]
- tags=json.loads(obj.tags_json), # type: ignore[attr-defined]
- source=obj.source, # type: ignore[attr-defined]
- evidence_commits=json.loads(obj.evidence_commits_json), # type: ignore[attr-defined]
- evidence_file=obj.evidence_file, # type: ignore[attr-defined]
- evidence_line=obj.evidence_line, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
- staleness_score=obj.staleness_score, # type: ignore[attr-defined]
- verification=obj.verification, # type: ignore[attr-defined]
- superseded_by=obj.superseded_by, # type: ignore[attr-defined]
- last_code_change=obj.last_code_change, # type: ignore[attr-defined]
- created_at=obj.created_at, # type: ignore[attr-defined]
- updated_at=obj.updated_at, # type: ignore[attr-defined]
- )
-
-
-class DecisionCreate(BaseModel):
- title: str
- context: str = ""
- decision: str = ""
- rationale: str = ""
- alternatives: list[str] = []
- consequences: list[str] = []
- affected_files: list[str] = []
- affected_modules: list[str] = []
- tags: list[str] = []
-
-
-class DecisionStatusUpdate(BaseModel):
- """PATCH body for /decisions/{id}.
-
- All fields are optional — clients can update status alone (the historical
- contract), the linked modules / files alone (governance editor), or both
- in a single request. Fields left at ``None`` are preserved.
- """
-
- status: str | None = None
- superseded_by: str | None = None
- affected_modules: list[str] | None = None
- affected_files: list[str] | None = None
-
-
-# ---------------------------------------------------------------------------
-# Decision evidence / lineage / graph (Phase 4)
-# ---------------------------------------------------------------------------
-
-
-class DecisionEvidenceResponse(BaseModel):
- """One provenance row supporting a decision record."""
-
- id: str
- source: str
- source_rank: int
- evidence_file: str | None
- evidence_line: int | None
- evidence_commit: str | None
- source_quote: str
- confidence: float
- verification: str
- created_at: str # ISO-8601
-
- @classmethod
- def from_orm(cls, obj: object) -> DecisionEvidenceResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- source=obj.source, # type: ignore[attr-defined]
- source_rank=obj.source_rank, # type: ignore[attr-defined]
- evidence_file=obj.evidence_file, # type: ignore[attr-defined]
- evidence_line=obj.evidence_line, # type: ignore[attr-defined]
- evidence_commit=obj.evidence_commit, # type: ignore[attr-defined]
- source_quote=obj.source_quote, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
- verification=obj.verification, # type: ignore[attr-defined]
- created_at=obj.created_at.isoformat(), # type: ignore[attr-defined]
- )
-
-
-class DecisionLineageEntry(BaseModel):
- """One node in a decision lineage chain (root → … → current)."""
-
- id: str
- title: str
- status: str
- source: str
- relation: str | None # edge kind that *reached* this node (None for the leaf)
-
-
-class DecisionGraphNode(BaseModel):
- """A decision record represented as a graph node."""
-
- id: str
- title: str
- status: str
- source: str
- confidence: float
- staleness_score: float
- verification: str
-
- @classmethod
- def from_orm(cls, obj: object) -> DecisionGraphNode:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- title=obj.title, # type: ignore[attr-defined]
- status=obj.status, # type: ignore[attr-defined]
- source=obj.source, # type: ignore[attr-defined]
- confidence=obj.confidence, # type: ignore[attr-defined]
- staleness_score=obj.staleness_score, # type: ignore[attr-defined]
- verification=obj.verification, # type: ignore[attr-defined]
- )
-
-
-class DecisionGraphEdge(BaseModel):
- """A typed directed edge between two decision records."""
-
- src: str
- dst: str
- kind: str
- confidence: float
- evidence: str
-
-
-class DecisionCodeEdge(BaseModel):
- """A link from a decision to a governed file or module."""
-
- decision_id: str
- node_id: str
- link_type: str # file | module
-
-
-class DecisionGraphResponse(BaseModel):
- """Full decision graph: nodes, decision→decision edges, decision→code edges."""
-
- nodes: list[DecisionGraphNode]
- decision_edges: list[DecisionGraphEdge]
- code_edges: list[DecisionCodeEdge]
-
-
-# ---------------------------------------------------------------------------
-# Chat
-# ---------------------------------------------------------------------------
-
-
-class ChatRequest(BaseModel):
- message: str
- conversation_id: str | None = None
- provider: str | None = None
- model: str | None = None
-
-
-class ConversationResponse(BaseModel):
- id: str
- repository_id: str
- title: str
- message_count: int = 0
- created_at: datetime
- updated_at: datetime
-
- @classmethod
- def from_orm(cls, obj: object, message_count: int = 0) -> ConversationResponse:
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- repository_id=obj.repository_id, # type: ignore[attr-defined]
- title=obj.title, # type: ignore[attr-defined]
- message_count=message_count,
- created_at=obj.created_at, # type: ignore[attr-defined]
- updated_at=obj.updated_at, # type: ignore[attr-defined]
- )
-
-
-class ChatMessageResponse(BaseModel):
- id: str
- conversation_id: str
- role: str
- content: dict
- created_at: datetime
-
- @classmethod
- def from_orm(cls, obj: object) -> ChatMessageResponse:
- content_str = obj.content_json # type: ignore[attr-defined]
- try:
- content = json.loads(content_str) if isinstance(content_str, str) else content_str
- except Exception:
- content = {"text": content_str}
- return cls(
- id=obj.id, # type: ignore[attr-defined]
- conversation_id=obj.conversation_id, # type: ignore[attr-defined]
- role=obj.role, # type: ignore[attr-defined]
- content=content,
- created_at=obj.created_at, # type: ignore[attr-defined]
- )
-
-
-# ---------------------------------------------------------------------------
-# Providers
-# ---------------------------------------------------------------------------
-
-
-class SetActiveProviderRequest(BaseModel):
- provider: str
- model: str | None = None
-
-
-class SetApiKeyRequest(BaseModel):
- api_key: str
-
-
-# ---------------------------------------------------------------------------
-# Cost Tracking
-# ---------------------------------------------------------------------------
-
-
-class CostGroupResponse(BaseModel):
- group: str
- calls: int
- input_tokens: int
- output_tokens: int
- cost_usd: float
-
-
-class CostSummaryResponse(BaseModel):
- total_cost_usd: float
- total_calls: int
- total_input_tokens: int
- total_output_tokens: int
- since: str | None
-
-
-# ---------------------------------------------------------------------------
-# Workspace
-# ---------------------------------------------------------------------------
-
-
-class WorkspaceRepoEntry(BaseModel):
- alias: str
- path: str
- is_primary: bool = False
- indexed_at: str | None = None
- last_commit_at_index: str | None = None
- # Per-repo stats (populated from each repo's wiki.db)
- repo_id: str | None = None
- file_count: int = 0
- symbol_count: int = 0
- page_count: int = 0
- doc_coverage_pct: float = 0.0
- hotspot_count: int = 0
- # Lifecycle status — surfaced so the web UI can render "needs index"
- # or "missing directory" affordances instead of silently dropping the
- # repo from the sidebar.
- # "indexed" — has .repowise/wiki.db with at least one Repository row
- # "needs_index" — directory exists but no .repowise/wiki.db yet
- # "missing_dir" — workspace config references a path that no longer exists
- status: str = "indexed"
- # Whether docs were generated for this repo. False means a user
- # action ("repowise update --repo <alias> --docs") is required to
- # populate the Docs/Overview tabs in the web UI.
- docs_enabled: bool = True
- # Optional skip reason captured in state.json — surfaced as a
- # transparency hint when docs are disabled.
- docs_skip_reason: str | None = None
-
-
-class WorkspaceCrossRepoSummary(BaseModel):
- co_change_count: int = 0
- package_dep_count: int = 0
- top_connections: list[dict] = []
-
-
-class WorkspaceContractSummary(BaseModel):
- total_contracts: int = 0
- total_links: int = 0
- by_type: dict[str, int] = {}
-
-
-class WorkspaceResponse(BaseModel):
- is_workspace: bool
- workspace_root: str | None = None
- workspace_name: str | None = None
- repos: list[WorkspaceRepoEntry] = []
- default_repo: str | None = None
- cross_repo_summary: WorkspaceCrossRepoSummary | None = None
- contract_summary: WorkspaceContractSummary | None = None
-
-
-class WorkspaceSyncResult(BaseModel):
- alias: str
- job_id: str | None = None
- repo_id: str | None = None
- status: str # "accepted", "skipped", "error"
- reason: str | None = None
-
-
-class WorkspaceSyncResponse(BaseModel):
- results: list[WorkspaceSyncResult]
- accepted: int = 0
- skipped: int = 0
- errors: int = 0
-
-
-class WorkspaceContractEntry(BaseModel):
- contract_id: str
- contract_type: str
- role: str
- repo: str
- file_path: str
- symbol_name: str
- confidence: float
- service: str | None = None
-
-
-class WorkspaceContractLinkEntry(BaseModel):
- contract_id: str
- contract_type: str
- match_type: str
- confidence: float
- provider_repo: str
- provider_file: str
- provider_symbol: str
- consumer_repo: str
- consumer_file: str
- consumer_symbol: str
-
-
-class WorkspaceContractsResponse(BaseModel):
- contracts: list[WorkspaceContractEntry]
- links: list[WorkspaceContractLinkEntry]
- total_contracts: int
- total_links: int
- by_type: dict[str, int] = {}
-
-
-class WorkspaceCoChangeEntry(BaseModel):
- source_repo: str
- source_file: str
- target_repo: str
- target_file: str
- strength: float
- frequency: int
- last_date: str
-
-
-class WorkspaceCoChangesResponse(BaseModel):
- co_changes: list[WorkspaceCoChangeEntry]
- total: int
-
-
-class WorkspaceGraphNode(BaseModel):
- repo_id: str
- name: str
- file_count: int = 0
- coverage_pct: float = 0.0
- health_score: int = 0
- top_language: str = "unknown"
-
-
-class WorkspaceGraphEdge(BaseModel):
- source: str
- target: str
- type: str # "contract" or "co_change"
- strength: float = 0.0
- label: str | None = None
-
-
-class WorkspaceGraphResponse(BaseModel):
- nodes: list[WorkspaceGraphNode] = []
- edges: list[WorkspaceGraphEdge] = []
-
-
-# ---------------------------------------------------------------------------
-# Owner / Contributor profile
-# ---------------------------------------------------------------------------
-
-
-class OwnerListEntry(BaseModel):
- """One row in the engineering-leader-facing owners directory."""
-
- key: str # stable identifier for the URL (email if known, else name)
- name: str
- email: str | None
- files_owned: int
- hotspots_owned: int
- silo_modules: int # modules where this owner is >80%
- dead_code_files_owned: int
- dead_code_lines_owned: int
- commit_count_90d: int # sum of per-file 90d commits attributed to this person
- last_commit_at: datetime | None
- bus_factor_risk_files: int # files they own where bus_factor <= 1
-
-
-class OwnerModuleRollup(BaseModel):
- module_path: str
- file_count: int
- hotspot_count: int
- dominant_pct: float # share of files in module owned by this person
-
-
-class OwnerFileEntry(BaseModel):
- file_path: str
- commit_count_90d: int
- churn_percentile: float # 0-100
- bus_factor: int
- is_hotspot: bool
- last_commit_at: datetime | None
- primary_owner_commit_pct: float | None
-
-
-class OwnerCoAuthor(BaseModel):
- name: str
- email: str | None
- shared_files: int
- co_change_strength: float # 0-1 fraction
-
-
-class OwnerProfileResponse(BaseModel):
- key: str
- name: str
- email: str | None
-
- # Headline metrics
- files_owned: int
- hotspots_owned: int
- silo_modules: int
- dead_code_files_owned: int
- dead_code_lines_owned: int
- commit_count_90d: int
- last_commit_at: datetime | None
- first_commit_at: datetime | None
- bus_factor_risk_files: int
-
- # 90d activity proxies (approximated from file-level totals weighted by
- # this person's share of commits on each file). They are estimates, not
- # exact per-author diff sizes — we never indexed per-author byte counts.
- lines_added_90d_est: int
- lines_deleted_90d_est: int
-
- # Breakdowns
- modules: list[OwnerModuleRollup]
- top_files: list[OwnerFileEntry]
- co_authors: list[OwnerCoAuthor]
-
- # Commit-category mix across files they touch (sum of categories).
- commit_categories: dict
-
-
-# ---------------------------------------------------------------------------
-# Module Health
-# ---------------------------------------------------------------------------
-
-
-class ModuleHealthOwner(BaseModel):
- name: str
- email: str | None
- file_count: int
- pct: float
-
-
-class ModuleHealthSummary(BaseModel):
- """One row in the per-module health rollup."""
-
- module_path: str
- file_count: int
- symbol_count: int
- hotspot_count: int
- dead_code_count: int
- dead_code_lines: int
- avg_churn_percentile: float # 0-100
- median_bus_factor: float
- min_bus_factor: int
- primary_owner: str | None
- primary_owner_pct: float
- is_silo: bool
- decision_count: int
- doc_coverage_pct: float
- # Composite 0–100 — higher = healthier (high docs, distributed ownership,
- # low dead code, manageable churn). Used to rank modules at a glance.
- health_score: float
-
-
-class ModuleHealthDetail(ModuleHealthSummary):
- """Single-module deep view with breakdowns."""
-
- owners: list[ModuleHealthOwner]
- top_hotspots: list[str]
- governing_decisions: list[str] # decision ids
- contributor_count: int
-
-
-# ---------------------------------------------------------------------------
-# Reviewer Suggestions
-# ---------------------------------------------------------------------------
-
-
-class ReviewerSuggestion(BaseModel):
- name: str
- email: str | None
- score: float # 0-1 composite
- recent_commits: int # commits in the last 90d across the requested paths
- owned_paths: list[str]
- co_change_paths: list[str]
- reasons: list[str]
-
-
-class ReviewerSuggestionsResponse(BaseModel):
- paths: list[str]
- suggestions: list[ReviewerSuggestion]
-
-
-# ---------------------------------------------------------------------------
-# C4 diagrams (L1 System Context, L2 Containers, L3 Components)
-# ---------------------------------------------------------------------------
-
-
-class C4PersonResponse(BaseModel):
- id: str
- name: str
- description: str = ""
-
-
-class C4SystemResponse(BaseModel):
- id: str
- name: str
- description: str = ""
-
-
-class C4ExternalSystemResponse(BaseModel):
- id: str
- name: str
- display_name: str
- category: str # framework | service | tool | library
- ecosystem: str
- version: str | None = None
-
-
-class C4ContainerResponse(BaseModel):
- id: str
- name: str
- path: str
- language: str
- file_count: int
- symbol_count: int
- hotspot_count: int = 0
- dead_count: int = 0
-
-
-class C4ComponentResponse(BaseModel):
- id: str
- name: str
- path: str
- container_id: str
- file_count: int
- symbol_count: int
-
-
-class C4RelationResponse(BaseModel):
- source_id: str
- target_id: str
- label: str = ""
- edge_count: int = 1
- edge_types: list[str] = Field(default_factory=list)
-
-
-class C4L1Response(BaseModel):
- system: C4SystemResponse
- people: list[C4PersonResponse]
- external_systems: list[C4ExternalSystemResponse]
- relations: list[C4RelationResponse]
-
-
-class C4L2Response(BaseModel):
- containers: list[C4ContainerResponse]
- external_systems: list[C4ExternalSystemResponse]
- relations: list[C4RelationResponse]
-
-
-class C4L3Response(BaseModel):
- container: C4ContainerResponse
- components: list[C4ComponentResponse]
- external_systems: list[C4ExternalSystemResponse]
- relations: list[C4RelationResponse]
-
-
-# ---------------------------------------------------------------------------
-# Architecture view
-# ---------------------------------------------------------------------------
-
-
-class ArchLayerResponse(BaseModel):
- id: str
- name: str
- description: str
- node_ids: list[str]
- file_count: int
- complexity_distribution: dict[str, int]
- health_score: float | None
-
-
-class ArchNodeResponse(BaseModel):
- id: str
- node_type: str
- name: str
- file_path: str | None
- line_range: list[int] | None
- summary: str
- complexity: str
- tags: list[str]
- language: str | None
- pagerank: float
- pagerank_percentile: float
- betweenness: float
- in_degree: int
- out_degree: int
- community_id: int | None
- is_entry_point: bool
- is_test: bool
- is_hotspot: bool
- is_dead: bool
- has_doc: bool
- primary_owner: str | None
- primary_owner_pct: float | None
- bus_factor: int | None
-
-
-class ArchEdgeResponse(BaseModel):
- source: str
- target: str
- edge_type: str
- direction: str
- weight: float
- confidence: float
-
-
-class ArchTourStepResponse(BaseModel):
- order: int
- title: str
- description: str
- node_ids: list[str]
-
-
-class ArchitectureViewResponse(BaseModel):
- project_name: str
- project_description: str
- layers: list[ArchLayerResponse]
- nodes: list[ArchNodeResponse]
- edges: list[ArchEdgeResponse]
- tour: list[ArchTourStepResponse]
- total_files: int
- total_symbols: int
- total_edges: int
- languages: list[str]
- frameworks: list[str]
- external_systems: list[C4ExternalSystemResponse]
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
new file mode 100644
index 000000000..cfb6e7b14
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/__init__.py
@@ -0,0 +1,270 @@
+"""Pydantic request/response models for the repowise REST API.
+
+This package was split out of the former single ``schemas.py`` module. Every
+public model is re-exported here so existing
+``from repowise.server.schemas import X`` imports keep working unchanged.
+"""
+
+from __future__ import annotations
+
+from .architecture import (
+ ArchEdgeResponse,
+ ArchitectureViewResponse,
+ ArchLayerResponse,
+ ArchNodeResponse,
+ ArchTourStepResponse,
+)
+from .blast_radius import (
+ BlastRadiusRequest,
+ BlastRadiusResponse,
+ CochangeWarning,
+ DirectRiskEntry,
+ ReviewerEntry,
+ TransitiveEntry,
+)
+from .c4 import (
+ C4ComponentResponse,
+ C4ContainerResponse,
+ C4ExternalSystemResponse,
+ C4L1Response,
+ C4L2Response,
+ C4L3Response,
+ C4PersonResponse,
+ C4RelationResponse,
+ C4SystemResponse,
+)
+from .chat import (
+ ChatMessageResponse,
+ ChatRequest,
+ ConversationResponse,
+)
+from .code_quality import (
+ DeadCodeFindingResponse,
+ DeadCodePatchRequest,
+ DeadCodeSummaryResponse,
+ RepoStatsResponse,
+ SecurityFindingResponse,
+)
+from .decisions import (
+ DecisionCodeEdge,
+ DecisionCreate,
+ DecisionEvidenceResponse,
+ DecisionGraphEdge,
+ DecisionGraphNode,
+ DecisionGraphResponse,
+ DecisionLineageEntry,
+ DecisionRecordResponse,
+ DecisionStatusUpdate,
+)
+from .git import (
+ GitMetadataResponse,
+ GitSummaryResponse,
+ HotspotResponse,
+ OwnershipEntry,
+)
+from .graph import (
+ ArchitectureEdgeResponse,
+ ArchitectureGraphResponse,
+ ArchitectureNodeResponse,
+ DeadCodeGraphNodeResponse,
+ DeadCodeGraphResponse,
+ EgoGraphResponse,
+ GraphEdgeResponse,
+ GraphExportResponse,
+ GraphNodeResponse,
+ HotFilesGraphResponse,
+ HotFilesNodeResponse,
+ ModuleEdgeResponse,
+ ModuleGraphResponse,
+ ModuleNodeResponse,
+ NodeSearchResult,
+)
+from .health import (
+ CoordinatorHealthResponse,
+ HealthResponse,
+)
+from .intelligence import (
+ CallerCalleeEntry,
+ CallersCalleesResponse,
+ CommunityDetailResponse,
+ CommunityMember,
+ CommunitySummaryItem,
+ ExecutionFlowEntry,
+ ExecutionFlowsResponse,
+ GraphMetricsResponse,
+ NeighboringCommunity,
+ SymbolNodeSummary,
+)
+from .ownership import (
+ KnowledgeMapOwner,
+ KnowledgeMapResponse,
+ KnowledgeMapSilo,
+ KnowledgeMapTarget,
+ ModuleHealthDetail,
+ ModuleHealthOwner,
+ ModuleHealthSummary,
+ OwnerCoAuthor,
+ OwnerFileEntry,
+ OwnerListEntry,
+ OwnerModuleRollup,
+ OwnerProfileResponse,
+ ReviewerSuggestion,
+ ReviewerSuggestionsResponse,
+)
+from .pages import (
+ JobResponse,
+ PageResponse,
+ PageVersionResponse,
+)
+from .pagination import Paginated
+from .repository import (
+ RepoCreate,
+ RepoResponse,
+ RepoUpdate,
+)
+from .search import (
+ SearchRequest,
+ SearchResultResponse,
+)
+from .symbols import (
+ SymbolImportanceComponents,
+ SymbolResponse,
+)
+from .ui_helpers import (
+ CostGroupResponse,
+ CostSummaryResponse,
+ SetActiveProviderRequest,
+ SetApiKeyRequest,
+ WebhookResponse,
+)
+from .workspace import (
+ WorkspaceCoChangeEntry,
+ WorkspaceCoChangesResponse,
+ WorkspaceContractEntry,
+ WorkspaceContractLinkEntry,
+ WorkspaceContractsResponse,
+ WorkspaceContractSummary,
+ WorkspaceCrossRepoSummary,
+ WorkspaceGraphEdge,
+ WorkspaceGraphNode,
+ WorkspaceGraphResponse,
+ WorkspaceRepoEntry,
+ WorkspaceResponse,
+ WorkspaceSyncResponse,
+ WorkspaceSyncResult,
+)
+
+__all__ = [
+ "ArchEdgeResponse",
+ "ArchLayerResponse",
+ "ArchNodeResponse",
+ "ArchTourStepResponse",
+ "ArchitectureEdgeResponse",
+ "ArchitectureGraphResponse",
+ "ArchitectureNodeResponse",
+ "ArchitectureViewResponse",
+ "BlastRadiusRequest",
+ "BlastRadiusResponse",
+ "C4ComponentResponse",
+ "C4ContainerResponse",
+ "C4ExternalSystemResponse",
+ "C4L1Response",
+ "C4L2Response",
+ "C4L3Response",
+ "C4PersonResponse",
+ "C4RelationResponse",
+ "C4SystemResponse",
+ "CallerCalleeEntry",
+ "CallersCalleesResponse",
+ "ChatMessageResponse",
+ "ChatRequest",
+ "CochangeWarning",
+ "CommunityDetailResponse",
+ "CommunityMember",
+ "CommunitySummaryItem",
+ "ConversationResponse",
+ "CoordinatorHealthResponse",
+ "CostGroupResponse",
+ "CostSummaryResponse",
+ "DeadCodeFindingResponse",
+ "DeadCodeGraphNodeResponse",
+ "DeadCodeGraphResponse",
+ "DeadCodePatchRequest",
+ "DeadCodeSummaryResponse",
+ "DecisionCodeEdge",
+ "DecisionCreate",
+ "DecisionEvidenceResponse",
+ "DecisionGraphEdge",
+ "DecisionGraphNode",
+ "DecisionGraphResponse",
+ "DecisionLineageEntry",
+ "DecisionRecordResponse",
+ "DecisionStatusUpdate",
+ "DirectRiskEntry",
+ "EgoGraphResponse",
+ "ExecutionFlowEntry",
+ "ExecutionFlowsResponse",
+ "GitMetadataResponse",
+ "GitSummaryResponse",
+ "GraphEdgeResponse",
+ "GraphExportResponse",
+ "GraphMetricsResponse",
+ "GraphNodeResponse",
+ "HealthResponse",
+ "HotFilesGraphResponse",
+ "HotFilesNodeResponse",
+ "HotspotResponse",
+ "JobResponse",
+ "KnowledgeMapOwner",
+ "KnowledgeMapResponse",
+ "KnowledgeMapSilo",
+ "KnowledgeMapTarget",
+ "ModuleEdgeResponse",
+ "ModuleGraphResponse",
+ "ModuleHealthDetail",
+ "ModuleHealthOwner",
+ "ModuleHealthSummary",
+ "ModuleNodeResponse",
+ "NeighboringCommunity",
+ "NodeSearchResult",
+ "OwnerCoAuthor",
+ "OwnerFileEntry",
+ "OwnerListEntry",
+ "OwnerModuleRollup",
+ "OwnerProfileResponse",
+ "OwnershipEntry",
+ "PageResponse",
+ "PageVersionResponse",
+ "Paginated",
+ "RepoCreate",
+ "RepoResponse",
+ "RepoStatsResponse",
+ "RepoUpdate",
+ "ReviewerEntry",
+ "ReviewerSuggestion",
+ "ReviewerSuggestionsResponse",
+ "SearchRequest",
+ "SearchResultResponse",
+ "SecurityFindingResponse",
+ "SetActiveProviderRequest",
+ "SetApiKeyRequest",
+ "SymbolImportanceComponents",
+ "SymbolNodeSummary",
+ "SymbolResponse",
+ "TransitiveEntry",
+ "WebhookResponse",
+ "WorkspaceCoChangeEntry",
+ "WorkspaceCoChangesResponse",
+ "WorkspaceContractEntry",
+ "WorkspaceContractLinkEntry",
+ "WorkspaceContractSummary",
+ "WorkspaceContractsResponse",
+ "WorkspaceCrossRepoSummary",
+ "WorkspaceGraphEdge",
+ "WorkspaceGraphNode",
+ "WorkspaceGraphResponse",
+ "WorkspaceRepoEntry",
+ "WorkspaceResponse",
+ "WorkspaceSyncResponse",
+ "WorkspaceSyncResult",
+]
diff --git a/packages/server/src/repowise/server/schemas/architecture.py b/packages/server/src/repowise/server/schemas/architecture.py
new file mode 100644
index 000000000..30fd4e7d9
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/architecture.py
@@ -0,0 +1,74 @@
+"""Architecture-view response models (layers, nodes, edges, tour)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .c4 import C4ExternalSystemResponse
+
+
+class ArchLayerResponse(BaseModel):
+ id: str
+ name: str
+ description: str
+ node_ids: list[str]
+ file_count: int
+ complexity_distribution: dict[str, int]
+ health_score: float | None
+
+
+class ArchNodeResponse(BaseModel):
+ id: str
+ node_type: str
+ name: str
+ file_path: str | None
+ line_range: list[int] | None
+ summary: str
+ complexity: str
+ tags: list[str]
+ language: str | None
+ pagerank: float
+ pagerank_percentile: float
+ betweenness: float
+ in_degree: int
+ out_degree: int
+ community_id: int | None
+ is_entry_point: bool
+ is_test: bool
+ is_hotspot: bool
+ is_dead: bool
+ has_doc: bool
+ primary_owner: str | None
+ primary_owner_pct: float | None
+ bus_factor: int | None
+
+
+class ArchEdgeResponse(BaseModel):
+ source: str
+ target: str
+ edge_type: str
+ direction: str
+ weight: float
+ confidence: float
+
+
+class ArchTourStepResponse(BaseModel):
+ order: int
+ title: str
+ description: str
+ node_ids: list[str]
+
+
+class ArchitectureViewResponse(BaseModel):
+ project_name: str
+ project_description: str
+ layers: list[ArchLayerResponse]
+ nodes: list[ArchNodeResponse]
+ edges: list[ArchEdgeResponse]
+ tour: list[ArchTourStepResponse]
+ total_files: int
+ total_symbols: int
+ total_edges: int
+ languages: list[str]
+ frameworks: list[str]
+ external_systems: list[C4ExternalSystemResponse]
diff --git a/packages/server/src/repowise/server/schemas/blast_radius.py b/packages/server/src/repowise/server/schemas/blast_radius.py
new file mode 100644
index 000000000..80c6cc5fd
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/blast_radius.py
@@ -0,0 +1,43 @@
+"""Blast-radius request/response models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class BlastRadiusRequest(BaseModel):
+ changed_files: list[str]
+ max_depth: int = Field(default=3, ge=1, le=10)
+
+
+class DirectRiskEntry(BaseModel):
+ path: str
+ risk_score: float
+ temporal_hotspot: float
+ centrality: float
+
+
+class TransitiveEntry(BaseModel):
+ path: str
+ depth: int
+
+
+class CochangeWarning(BaseModel):
+ changed: str
+ missing_partner: str
+ score: float
+
+
+class ReviewerEntry(BaseModel):
+ email: str
+ files: int
+ ownership_pct: float
+
+
+class BlastRadiusResponse(BaseModel):
+ direct_risks: list[DirectRiskEntry]
+ transitive_affected: list[TransitiveEntry]
+ cochange_warnings: list[CochangeWarning]
+ recommended_reviewers: list[ReviewerEntry]
+ test_gaps: list[str]
+ overall_risk_score: float
diff --git a/packages/server/src/repowise/server/schemas/c4.py b/packages/server/src/repowise/server/schemas/c4.py
new file mode 100644
index 000000000..3a1065a29
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/c4.py
@@ -0,0 +1,74 @@
+"""C4 diagram response models (L1 System Context, L2 Containers, L3 Components)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class C4PersonResponse(BaseModel):
+ id: str
+ name: str
+ description: str = ""
+
+
+class C4SystemResponse(BaseModel):
+ id: str
+ name: str
+ description: str = ""
+
+
+class C4ExternalSystemResponse(BaseModel):
+ id: str
+ name: str
+ display_name: str
+ category: str # framework | service | tool | library
+ ecosystem: str
+ version: str | None = None
+
+
+class C4ContainerResponse(BaseModel):
+ id: str
+ name: str
+ path: str
+ language: str
+ file_count: int
+ symbol_count: int
+ hotspot_count: int = 0
+ dead_count: int = 0
+
+
+class C4ComponentResponse(BaseModel):
+ id: str
+ name: str
+ path: str
+ container_id: str
+ file_count: int
+ symbol_count: int
+
+
+class C4RelationResponse(BaseModel):
+ source_id: str
+ target_id: str
+ label: str = ""
+ edge_count: int = 1
+ edge_types: list[str] = Field(default_factory=list)
+
+
+class C4L1Response(BaseModel):
+ system: C4SystemResponse
+ people: list[C4PersonResponse]
+ external_systems: list[C4ExternalSystemResponse]
+ relations: list[C4RelationResponse]
+
+
+class C4L2Response(BaseModel):
+ containers: list[C4ContainerResponse]
+ external_systems: list[C4ExternalSystemResponse]
+ relations: list[C4RelationResponse]
+
+
+class C4L3Response(BaseModel):
+ container: C4ContainerResponse
+ components: list[C4ComponentResponse]
+ external_systems: list[C4ExternalSystemResponse]
+ relations: list[C4RelationResponse]
diff --git a/packages/server/src/repowise/server/schemas/chat.py b/packages/server/src/repowise/server/schemas/chat.py
new file mode 100644
index 000000000..763dc5b9b
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/chat.py
@@ -0,0 +1,58 @@
+"""Chat request/response models."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class ChatRequest(BaseModel):
+ message: str
+ conversation_id: str | None = None
+ provider: str | None = None
+ model: str | None = None
+
+
+class ConversationResponse(BaseModel):
+ id: str
+ repository_id: str
+ title: str
+ message_count: int = 0
+ created_at: datetime
+ updated_at: datetime
+
+ @classmethod
+ def from_orm(cls, obj: object, message_count: int = 0) -> ConversationResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ repository_id=obj.repository_id, # type: ignore[attr-defined]
+ title=obj.title, # type: ignore[attr-defined]
+ message_count=message_count,
+ created_at=obj.created_at, # type: ignore[attr-defined]
+ updated_at=obj.updated_at, # type: ignore[attr-defined]
+ )
+
+
+class ChatMessageResponse(BaseModel):
+ id: str
+ conversation_id: str
+ role: str
+ content: dict
+ created_at: datetime
+
+ @classmethod
+ def from_orm(cls, obj: object) -> ChatMessageResponse:
+ content_str = obj.content_json # type: ignore[attr-defined]
+ try:
+ content = json.loads(content_str) if isinstance(content_str, str) else content_str
+ except Exception:
+ content = {"text": content_str}
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ conversation_id=obj.conversation_id, # type: ignore[attr-defined]
+ role=obj.role, # type: ignore[attr-defined]
+ content=content,
+ created_at=obj.created_at, # type: ignore[attr-defined]
+ )
diff --git a/packages/server/src/repowise/server/schemas/code_quality.py b/packages/server/src/repowise/server/schemas/code_quality.py
new file mode 100644
index 000000000..d732941d0
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/code_quality.py
@@ -0,0 +1,70 @@
+"""Dead-code, security and repo-stats response models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class DeadCodeFindingResponse(BaseModel):
+ id: str
+ kind: str
+ file_path: str
+ symbol_name: str | None
+ symbol_kind: str | None
+ confidence: float
+ reason: str
+ lines: int
+ safe_to_delete: bool
+ primary_owner: str | None
+ status: str
+ note: str | None
+
+ @classmethod
+ def from_orm(cls, obj: object) -> DeadCodeFindingResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ kind=obj.kind, # type: ignore[attr-defined]
+ file_path=obj.file_path, # type: ignore[attr-defined]
+ symbol_name=obj.symbol_name, # type: ignore[attr-defined]
+ symbol_kind=obj.symbol_kind, # type: ignore[attr-defined]
+ confidence=obj.confidence, # type: ignore[attr-defined]
+ reason=obj.reason, # type: ignore[attr-defined]
+ lines=obj.lines, # type: ignore[attr-defined]
+ safe_to_delete=obj.safe_to_delete, # type: ignore[attr-defined]
+ primary_owner=obj.primary_owner, # type: ignore[attr-defined]
+ status=obj.status, # type: ignore[attr-defined]
+ note=obj.note, # type: ignore[attr-defined]
+ )
+
+
+class DeadCodePatchRequest(BaseModel):
+ status: str
+ note: str | None = None
+
+
+class DeadCodeSummaryResponse(BaseModel):
+ total_findings: int
+ confidence_summary: dict
+ deletable_lines: int
+ total_lines: int
+ by_kind: dict
+
+
+class SecurityFindingResponse(BaseModel):
+ id: int
+ file_path: str
+ kind: str
+ severity: str
+ snippet: str | None
+ detected_at: datetime
+
+
+class RepoStatsResponse(BaseModel):
+ file_count: int
+ symbol_count: int
+ entry_point_count: int
+ doc_coverage_pct: float
+ freshness_score: float
+ dead_export_count: int
diff --git a/packages/server/src/repowise/server/schemas/decisions.py b/packages/server/src/repowise/server/schemas/decisions.py
new file mode 100644
index 000000000..d4b5b3f2b
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/decisions.py
@@ -0,0 +1,178 @@
+"""Decision-record request/response models (records, evidence, lineage, graph)."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class DecisionRecordResponse(BaseModel):
+ id: str
+ repository_id: str
+ title: str
+ status: str
+ context: str
+ decision: str
+ rationale: str
+ alternatives: list[str]
+ consequences: list[str]
+ affected_files: list[str]
+ affected_modules: list[str]
+ tags: list[str]
+ source: str
+ evidence_commits: list[str]
+ evidence_file: str | None
+ evidence_line: int | None
+ confidence: float
+ staleness_score: float
+ verification: str = "unverified"
+ superseded_by: str | None
+ last_code_change: datetime | None
+ created_at: datetime
+ updated_at: datetime
+
+ @classmethod
+ def from_orm(cls, obj: object) -> DecisionRecordResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ repository_id=obj.repository_id, # type: ignore[attr-defined]
+ title=obj.title, # type: ignore[attr-defined]
+ status=obj.status, # type: ignore[attr-defined]
+ context=obj.context, # type: ignore[attr-defined]
+ decision=obj.decision, # type: ignore[attr-defined]
+ rationale=obj.rationale, # type: ignore[attr-defined]
+ alternatives=json.loads(obj.alternatives_json), # type: ignore[attr-defined]
+ consequences=json.loads(obj.consequences_json), # type: ignore[attr-defined]
+ affected_files=json.loads(obj.affected_files_json), # type: ignore[attr-defined]
+ affected_modules=json.loads(obj.affected_modules_json), # type: ignore[attr-defined]
+ tags=json.loads(obj.tags_json), # type: ignore[attr-defined]
+ source=obj.source, # type: ignore[attr-defined]
+ evidence_commits=json.loads(obj.evidence_commits_json), # type: ignore[attr-defined]
+ evidence_file=obj.evidence_file, # type: ignore[attr-defined]
+ evidence_line=obj.evidence_line, # type: ignore[attr-defined]
+ confidence=obj.confidence, # type: ignore[attr-defined]
+ staleness_score=obj.staleness_score, # type: ignore[attr-defined]
+ verification=obj.verification, # type: ignore[attr-defined]
+ superseded_by=obj.superseded_by, # type: ignore[attr-defined]
+ last_code_change=obj.last_code_change, # type: ignore[attr-defined]
+ created_at=obj.created_at, # type: ignore[attr-defined]
+ updated_at=obj.updated_at, # type: ignore[attr-defined]
+ )
+
+
+class DecisionCreate(BaseModel):
+ title: str
+ context: str = ""
+ decision: str = ""
+ rationale: str = ""
+ alternatives: list[str] = []
+ consequences: list[str] = []
+ affected_files: list[str] = []
+ affected_modules: list[str] = []
+ tags: list[str] = []
+
+
+class DecisionStatusUpdate(BaseModel):
+ """PATCH body for /decisions/{id}.
+
+ All fields are optional — clients can update status alone (the historical
+ contract), the linked modules / files alone (governance editor), or both
+ in a single request. Fields left at ``None`` are preserved.
+ """
+
+ status: str | None = None
+ superseded_by: str | None = None
+ affected_modules: list[str] | None = None
+ affected_files: list[str] | None = None
+
+
+class DecisionEvidenceResponse(BaseModel):
+ """One provenance row supporting a decision record."""
+
+ id: str
+ source: str
+ source_rank: int
+ evidence_file: str | None
+ evidence_line: int | None
+ evidence_commit: str | None
+ source_quote: str
+ confidence: float
+ verification: str
+ created_at: str # ISO-8601
+
+ @classmethod
+ def from_orm(cls, obj: object) -> DecisionEvidenceResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ source=obj.source, # type: ignore[attr-defined]
+ source_rank=obj.source_rank, # type: ignore[attr-defined]
+ evidence_file=obj.evidence_file, # type: ignore[attr-defined]
+ evidence_line=obj.evidence_line, # type: ignore[attr-defined]
+ evidence_commit=obj.evidence_commit, # type: ignore[attr-defined]
+ source_quote=obj.source_quote, # type: ignore[attr-defined]
+ confidence=obj.confidence, # type: ignore[attr-defined]
+ verification=obj.verification, # type: ignore[attr-defined]
+ created_at=obj.created_at.isoformat(), # type: ignore[attr-defined]
+ )
+
+
+class DecisionLineageEntry(BaseModel):
+ """One node in a decision lineage chain (root → … → current)."""
+
+ id: str
+ title: str
+ status: str
+ source: str
+ relation: str | None # edge kind that *reached* this node (None for the leaf)
+
+
+class DecisionGraphNode(BaseModel):
+ """A decision record represented as a graph node."""
+
+ id: str
+ title: str
+ status: str
+ source: str
+ confidence: float
+ staleness_score: float
+ verification: str
+
+ @classmethod
+ def from_orm(cls, obj: object) -> DecisionGraphNode:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ title=obj.title, # type: ignore[attr-defined]
+ status=obj.status, # type: ignore[attr-defined]
+ source=obj.source, # type: ignore[attr-defined]
+ confidence=obj.confidence, # type: ignore[attr-defined]
+ staleness_score=obj.staleness_score, # type: ignore[attr-defined]
+ verification=obj.verification, # type: ignore[attr-defined]
+ )
+
+
+class DecisionGraphEdge(BaseModel):
+ """A typed directed edge between two decision records."""
+
+ src: str
+ dst: str
+ kind: str
+ confidence: float
+ evidence: str
+
+
+class DecisionCodeEdge(BaseModel):
+ """A link from a decision to a governed file or module."""
+
+ decision_id: str
+ node_id: str
+ link_type: str # file | module
+
+
+class DecisionGraphResponse(BaseModel):
+ """Full decision graph: nodes, decision→decision edges, decision→code edges."""
+
+ nodes: list[DecisionGraphNode]
+ decision_edges: list[DecisionGraphEdge]
+ code_edges: list[DecisionCodeEdge]
diff --git a/packages/server/src/repowise/server/schemas/git.py b/packages/server/src/repowise/server/schemas/git.py
new file mode 100644
index 000000000..8d9aa4ef1
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/git.py
@@ -0,0 +1,111 @@
+"""Git-intelligence response models."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class GitMetadataResponse(BaseModel):
+ file_path: str
+ commit_count_total: int
+ commit_count_90d: int
+ commit_count_30d: int
+ first_commit_at: datetime | None
+ last_commit_at: datetime | None
+ primary_owner_name: str | None
+ primary_owner_email: str | None
+ primary_owner_commit_pct: float | None
+ recent_owner_name: str | None
+ recent_owner_commit_pct: float | None
+ top_authors: list[dict]
+ significant_commits: list[dict]
+ co_change_partners: list[dict]
+ is_hotspot: bool
+ is_stable: bool
+ churn_percentile: float
+ age_days: int
+ bus_factor: int
+ contributor_count: int
+ lines_added_90d: int
+ lines_deleted_90d: int
+ avg_commit_size: float
+ commit_categories: dict
+ merge_commit_count_90d: int
+ test_gap: bool | None = None
+
+ @classmethod
+ def from_orm(cls, obj: object) -> GitMetadataResponse:
+ return cls(
+ file_path=obj.file_path, # type: ignore[attr-defined]
+ commit_count_total=obj.commit_count_total, # type: ignore[attr-defined]
+ commit_count_90d=obj.commit_count_90d, # type: ignore[attr-defined]
+ commit_count_30d=obj.commit_count_30d, # type: ignore[attr-defined]
+ first_commit_at=obj.first_commit_at, # type: ignore[attr-defined]
+ last_commit_at=obj.last_commit_at, # type: ignore[attr-defined]
+ primary_owner_name=obj.primary_owner_name, # type: ignore[attr-defined]
+ primary_owner_email=obj.primary_owner_email, # type: ignore[attr-defined]
+ primary_owner_commit_pct=obj.primary_owner_commit_pct, # type: ignore[attr-defined]
+ recent_owner_name=obj.recent_owner_name, # type: ignore[attr-defined]
+ recent_owner_commit_pct=obj.recent_owner_commit_pct, # type: ignore[attr-defined]
+ top_authors=json.loads(obj.top_authors_json), # type: ignore[attr-defined]
+ significant_commits=json.loads(obj.significant_commits_json), # type: ignore[attr-defined]
+ co_change_partners=json.loads(obj.co_change_partners_json), # type: ignore[attr-defined]
+ is_hotspot=obj.is_hotspot, # type: ignore[attr-defined]
+ is_stable=obj.is_stable, # type: ignore[attr-defined]
+ # Normalize 0-1 -> 0-100 to match the rest of the HTTP API.
+ churn_percentile=(obj.churn_percentile or 0.0) * 100.0, # type: ignore[attr-defined]
+ age_days=obj.age_days, # type: ignore[attr-defined]
+ bus_factor=obj.bus_factor or 0, # type: ignore[attr-defined]
+ contributor_count=obj.contributor_count or 0, # type: ignore[attr-defined]
+ lines_added_90d=obj.lines_added_90d or 0, # type: ignore[attr-defined]
+ lines_deleted_90d=obj.lines_deleted_90d or 0, # type: ignore[attr-defined]
+ avg_commit_size=obj.avg_commit_size or 0.0, # type: ignore[attr-defined]
+ commit_categories=json.loads(obj.commit_categories_json)
+ if obj.commit_categories_json
+ else {}, # type: ignore[attr-defined]
+ merge_commit_count_90d=obj.merge_commit_count_90d or 0, # type: ignore[attr-defined]
+ )
+
+
+class HotspotResponse(BaseModel):
+ file_path: str
+ commit_count_total: int = 0
+ commit_count_90d: int
+ commit_count_30d: int
+ churn_percentile: float
+ temporal_hotspot_score: float | None = None
+ primary_owner: str | None
+ primary_owner_commit_pct: float | None = None
+ recent_owner_name: str | None = None
+ recent_owner_commit_pct: float | None = None
+ is_hotspot: bool
+ is_stable: bool
+ bus_factor: int
+ contributor_count: int
+ lines_added_90d: int
+ lines_deleted_90d: int
+ avg_commit_size: float
+ commit_categories: dict
+ merge_commit_count_90d: int = 0
+ commit_count_capped: bool = False
+ age_days: int = 0
+ last_commit_at: datetime | None = None
+
+
+class OwnershipEntry(BaseModel):
+ module_path: str
+ primary_owner: str | None
+ owner_pct: float | None
+ file_count: int
+ is_silo: bool
+
+
+class GitSummaryResponse(BaseModel):
+ total_files: int
+ hotspot_count: int
+ stable_count: int
+ average_churn_percentile: float
+ top_owners: list[dict]
diff --git a/packages/server/src/repowise/server/schemas/graph.py b/packages/server/src/repowise/server/schemas/graph.py
new file mode 100644
index 000000000..cb63124e0
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/graph.py
@@ -0,0 +1,125 @@
+"""Graph-export response models (file/symbol graph, module graph, ego graph,
+dead-code graph, hot-files graph and the community super-node graph)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .git import GitMetadataResponse
+
+
+class GraphNodeResponse(BaseModel):
+ node_id: str
+ node_type: str
+ language: str
+ symbol_count: int
+ pagerank: float
+ betweenness: float
+ community_id: int
+ is_test: bool = False
+ is_entry_point: bool = False
+ has_doc: bool = False
+ # Cross-link signals (populated by _collect_node_signals)
+ is_hotspot: bool = False
+ churn_percentile: float | None = None
+ is_dead: bool = False
+ dead_confidence: float | None = None
+ has_decision: bool = False
+ primary_owner: str | None = None
+
+
+class GraphEdgeResponse(BaseModel):
+ source: str
+ target: str
+ imported_names: list[str]
+
+
+class GraphExportResponse(BaseModel):
+ nodes: list[GraphNodeResponse]
+ links: list[GraphEdgeResponse]
+ # When the graph is too large to return in full, the server caps the response
+ # to top-N nodes by PageRank. Clients should surface a banner.
+ truncated: bool = False
+ total_node_count: int | None = None
+
+
+# Architecture / community super-node graph
+class ArchitectureNodeResponse(BaseModel):
+ community_id: int
+ label: str
+ cohesion: float
+ member_count: int
+ top_file: str
+ avg_pagerank: float
+ hotspot_count: int = 0
+ dead_count: int = 0
+ has_decision: bool = False
+ doc_coverage_pct: float = 0.0
+ languages: list[str] = []
+
+
+class ArchitectureEdgeResponse(BaseModel):
+ source: int
+ target: int
+ edge_count: int
+
+
+class ArchitectureGraphResponse(BaseModel):
+ nodes: list[ArchitectureNodeResponse]
+ edges: list[ArchitectureEdgeResponse]
+
+
+class EgoGraphResponse(BaseModel):
+ nodes: list[GraphNodeResponse]
+ links: list[GraphEdgeResponse]
+ center_node_id: str
+ center_git_meta: GitMetadataResponse | None
+ inbound_count: int
+ outbound_count: int
+
+
+class NodeSearchResult(BaseModel):
+ node_id: str
+ language: str
+ symbol_count: int
+
+
+class DeadCodeGraphNodeResponse(GraphNodeResponse):
+ confidence_group: str # "certain" | "likely" | "neighbor"
+
+
+class DeadCodeGraphResponse(BaseModel):
+ nodes: list[DeadCodeGraphNodeResponse]
+ links: list[GraphEdgeResponse]
+
+
+class HotFilesNodeResponse(GraphNodeResponse):
+ commit_count: int
+
+
+class HotFilesGraphResponse(BaseModel):
+ nodes: list[HotFilesNodeResponse]
+ links: list[GraphEdgeResponse]
+
+
+class ModuleNodeResponse(BaseModel):
+ module_id: str
+ file_count: int
+ symbol_count: int
+ avg_pagerank: float
+ doc_coverage_pct: float
+ hotspot_count: int = 0
+ dead_count: int = 0
+ has_decision: bool = False
+ primary_owner: str | None = None
+
+
+class ModuleEdgeResponse(BaseModel):
+ source: str
+ target: str
+ edge_count: int
+
+
+class ModuleGraphResponse(BaseModel):
+ nodes: list[ModuleNodeResponse]
+ edges: list[ModuleEdgeResponse]
diff --git a/packages/server/src/repowise/server/schemas/health.py b/packages/server/src/repowise/server/schemas/health.py
new file mode 100644
index 000000000..126bf3894
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/health.py
@@ -0,0 +1,19 @@
+"""Health / liveness response models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HealthResponse(BaseModel):
+ status: str
+ db: str
+ version: str
+
+
+class CoordinatorHealthResponse(BaseModel):
+ sql_pages: int | None
+ vector_count: int | None
+ graph_nodes: int | None
+ drift_pct: float | None
+ status: str # "ok" | "warning" | "critical"
diff --git a/packages/server/src/repowise/server/schemas/intelligence.py b/packages/server/src/repowise/server/schemas/intelligence.py
new file mode 100644
index 000000000..73d79cfc9
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/intelligence.py
@@ -0,0 +1,97 @@
+"""Graph-intelligence response models (callers/callees, communities,
+node metrics and execution flows)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class SymbolNodeSummary(BaseModel):
+ symbol_id: str
+ name: str
+ kind: str
+ file: str
+ start_line: int | None = None
+ signature: str | None = None
+
+
+class CallerCalleeEntry(BaseModel):
+ symbol_id: str
+ name: str
+ kind: str
+ file: str
+ start_line: int | None = None
+ edge_type: str
+ confidence: float
+
+
+class CallersCalleesResponse(BaseModel):
+ symbol_id: str
+ symbol: SymbolNodeSummary
+ callers: list[CallerCalleeEntry]
+ callees: list[CallerCalleeEntry]
+ caller_count: int
+ callee_count: int
+ truncated: bool
+
+
+class CommunityMember(BaseModel):
+ path: str
+ pagerank: float
+ is_entry_point: bool
+
+
+class NeighboringCommunity(BaseModel):
+ community_id: int
+ label: str
+ cross_edge_count: int
+
+
+class CommunityDetailResponse(BaseModel):
+ community_id: int
+ label: str
+ cohesion: float
+ member_count: int
+ members: list[CommunityMember]
+ truncated: bool
+ neighboring_communities: list[NeighboringCommunity]
+
+
+class CommunitySummaryItem(BaseModel):
+ community_id: int
+ label: str
+ cohesion: float
+ member_count: int
+ top_file: str
+
+
+class GraphMetricsResponse(BaseModel):
+ target: str
+ node_type: str
+ pagerank: float
+ pagerank_percentile: int
+ betweenness: float
+ betweenness_percentile: int
+ community_id: int
+ community_label: str | None
+ is_entry_point: bool
+ in_degree: int
+ out_degree: int
+ entry_point_score: float | None = None
+ kind: str | None = None
+ file: str | None = None
+
+
+class ExecutionFlowEntry(BaseModel):
+ entry_point: str
+ entry_point_name: str
+ entry_point_score: float
+ trace: list[str]
+ depth: int
+ crosses_community: bool
+ communities_visited: list[int]
+
+
+class ExecutionFlowsResponse(BaseModel):
+ total_entry_points: int
+ flows: list[ExecutionFlowEntry]
diff --git a/packages/server/src/repowise/server/schemas/ownership.py b/packages/server/src/repowise/server/schemas/ownership.py
new file mode 100644
index 000000000..8fb8ecab7
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/ownership.py
@@ -0,0 +1,156 @@
+"""Ownership, knowledge-map, module-health and reviewer-suggestion models."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class KnowledgeMapOwner(BaseModel):
+ email: str
+ name: str
+ files_owned: int
+ percentage: float
+
+
+class KnowledgeMapSilo(BaseModel):
+ file_path: str
+ owner_email: str
+ owner_pct: float
+
+
+class KnowledgeMapTarget(BaseModel):
+ path: str
+ pagerank: float
+ doc_words: int
+
+
+class KnowledgeMapResponse(BaseModel):
+ top_owners: list[KnowledgeMapOwner]
+ knowledge_silos: list[KnowledgeMapSilo]
+ onboarding_targets: list[KnowledgeMapTarget]
+
+
+class OwnerListEntry(BaseModel):
+ """One row in the engineering-leader-facing owners directory."""
+
+ key: str # stable identifier for the URL (email if known, else name)
+ name: str
+ email: str | None
+ files_owned: int
+ hotspots_owned: int
+ silo_modules: int # modules where this owner is >80%
+ dead_code_files_owned: int
+ dead_code_lines_owned: int
+ commit_count_90d: int # sum of per-file 90d commits attributed to this person
+ last_commit_at: datetime | None
+ bus_factor_risk_files: int # files they own where bus_factor <= 1
+
+
+class OwnerModuleRollup(BaseModel):
+ module_path: str
+ file_count: int
+ hotspot_count: int
+ dominant_pct: float # share of files in module owned by this person
+
+
+class OwnerFileEntry(BaseModel):
+ file_path: str
+ commit_count_90d: int
+ churn_percentile: float # 0-100
+ bus_factor: int
+ is_hotspot: bool
+ last_commit_at: datetime | None
+ primary_owner_commit_pct: float | None
+
+
+class OwnerCoAuthor(BaseModel):
+ name: str
+ email: str | None
+ shared_files: int
+ co_change_strength: float # 0-1 fraction
+
+
+class OwnerProfileResponse(BaseModel):
+ key: str
+ name: str
+ email: str | None
+
+ # Headline metrics
+ files_owned: int
+ hotspots_owned: int
+ silo_modules: int
+ dead_code_files_owned: int
+ dead_code_lines_owned: int
+ commit_count_90d: int
+ last_commit_at: datetime | None
+ first_commit_at: datetime | None
+ bus_factor_risk_files: int
+
+ # 90d activity proxies (approximated from file-level totals weighted by
+ # this person's share of commits on each file). They are estimates, not
+ # exact per-author diff sizes — we never indexed per-author byte counts.
+ lines_added_90d_est: int
+ lines_deleted_90d_est: int
+
+ # Breakdowns
+ modules: list[OwnerModuleRollup]
+ top_files: list[OwnerFileEntry]
+ co_authors: list[OwnerCoAuthor]
+
+ # Commit-category mix across files they touch (sum of categories).
+ commit_categories: dict
+
+
+class ModuleHealthOwner(BaseModel):
+ name: str
+ email: str | None
+ file_count: int
+ pct: float
+
+
+class ModuleHealthSummary(BaseModel):
+ """One row in the per-module health rollup."""
+
+ module_path: str
+ file_count: int
+ symbol_count: int
+ hotspot_count: int
+ dead_code_count: int
+ dead_code_lines: int
+ avg_churn_percentile: float # 0-100
+ median_bus_factor: float
+ min_bus_factor: int
+ primary_owner: str | None
+ primary_owner_pct: float
+ is_silo: bool
+ decision_count: int
+ doc_coverage_pct: float
+ # Composite 0-100 - higher = healthier (high docs, distributed ownership,
+ # low dead code, manageable churn). Used to rank modules at a glance.
+ health_score: float
+
+
+class ModuleHealthDetail(ModuleHealthSummary):
+ """Single-module deep view with breakdowns."""
+
+ owners: list[ModuleHealthOwner]
+ top_hotspots: list[str]
+ governing_decisions: list[str] # decision ids
+ contributor_count: int
+
+
+class ReviewerSuggestion(BaseModel):
+ name: str
+ email: str | None
+ score: float # 0-1 composite
+ recent_commits: int # commits in the last 90d across the requested paths
+ owned_paths: list[str]
+ co_change_paths: list[str]
+ reasons: list[str]
+
+
+class ReviewerSuggestionsResponse(BaseModel):
+ paths: list[str]
+ suggestions: list[ReviewerSuggestion]
diff --git a/packages/server/src/repowise/server/schemas/pages.py b/packages/server/src/repowise/server/schemas/pages.py
new file mode 100644
index 000000000..9e9f5217f
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/pages.py
@@ -0,0 +1,128 @@
+"""Generated-page and generation-job response models."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class PageResponse(BaseModel):
+ id: str
+ repository_id: str
+ page_type: str
+ title: str
+ content: str
+ target_path: str
+ source_hash: str
+ model_name: str
+ provider_name: str
+ input_tokens: int
+ output_tokens: int
+ cached_tokens: int
+ generation_level: int
+ version: int
+ confidence: float
+ freshness_status: str
+ metadata: dict
+ human_notes: str | None = None
+ created_at: datetime
+ updated_at: datetime
+
+ @classmethod
+ def from_orm(cls, obj: object) -> PageResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ repository_id=obj.repository_id, # type: ignore[attr-defined]
+ page_type=obj.page_type, # type: ignore[attr-defined]
+ title=obj.title, # type: ignore[attr-defined]
+ content=obj.content, # type: ignore[attr-defined]
+ target_path=obj.target_path, # type: ignore[attr-defined]
+ source_hash=obj.source_hash, # type: ignore[attr-defined]
+ model_name=obj.model_name, # type: ignore[attr-defined]
+ provider_name=obj.provider_name, # type: ignore[attr-defined]
+ input_tokens=obj.input_tokens, # type: ignore[attr-defined]
+ output_tokens=obj.output_tokens, # type: ignore[attr-defined]
+ cached_tokens=obj.cached_tokens, # type: ignore[attr-defined]
+ generation_level=obj.generation_level, # type: ignore[attr-defined]
+ version=obj.version, # type: ignore[attr-defined]
+ confidence=obj.confidence, # type: ignore[attr-defined]
+ freshness_status=obj.freshness_status, # type: ignore[attr-defined]
+ metadata=json.loads(obj.metadata_json), # type: ignore[attr-defined]
+ human_notes=obj.human_notes, # type: ignore[attr-defined]
+ created_at=obj.created_at, # type: ignore[attr-defined]
+ updated_at=obj.updated_at, # type: ignore[attr-defined]
+ )
+
+
+class PageVersionResponse(BaseModel):
+ id: str
+ page_id: str
+ version: int
+ page_type: str
+ title: str
+ content: str
+ source_hash: str
+ model_name: str
+ provider_name: str
+ input_tokens: int
+ output_tokens: int
+ confidence: float
+ archived_at: datetime
+
+ @classmethod
+ def from_orm(cls, obj: object) -> PageVersionResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ page_id=obj.page_id, # type: ignore[attr-defined]
+ version=obj.version, # type: ignore[attr-defined]
+ page_type=obj.page_type, # type: ignore[attr-defined]
+ title=obj.title, # type: ignore[attr-defined]
+ content=obj.content, # type: ignore[attr-defined]
+ source_hash=obj.source_hash, # type: ignore[attr-defined]
+ model_name=obj.model_name, # type: ignore[attr-defined]
+ provider_name=obj.provider_name, # type: ignore[attr-defined]
+ input_tokens=obj.input_tokens, # type: ignore[attr-defined]
+ output_tokens=obj.output_tokens, # type: ignore[attr-defined]
+ confidence=obj.confidence, # type: ignore[attr-defined]
+ archived_at=obj.archived_at, # type: ignore[attr-defined]
+ )
+
+
+class JobResponse(BaseModel):
+ id: str
+ repository_id: str
+ status: str
+ provider_name: str
+ model_name: str
+ total_pages: int
+ completed_pages: int
+ failed_pages: int
+ current_level: int
+ error_message: str | None
+ config: dict
+ created_at: datetime
+ updated_at: datetime
+ started_at: datetime | None
+ finished_at: datetime | None
+
+ @classmethod
+ def from_orm(cls, obj: object) -> JobResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ repository_id=obj.repository_id, # type: ignore[attr-defined]
+ status=obj.status, # type: ignore[attr-defined]
+ provider_name=obj.provider_name, # type: ignore[attr-defined]
+ model_name=obj.model_name, # type: ignore[attr-defined]
+ total_pages=obj.total_pages, # type: ignore[attr-defined]
+ completed_pages=obj.completed_pages, # type: ignore[attr-defined]
+ failed_pages=obj.failed_pages, # type: ignore[attr-defined]
+ current_level=obj.current_level, # type: ignore[attr-defined]
+ error_message=obj.error_message, # type: ignore[attr-defined]
+ config=json.loads(obj.config_json), # type: ignore[attr-defined]
+ created_at=obj.created_at, # type: ignore[attr-defined]
+ updated_at=obj.updated_at, # type: ignore[attr-defined]
+ started_at=obj.started_at, # type: ignore[attr-defined]
+ finished_at=obj.finished_at, # type: ignore[attr-defined]
+ )
diff --git a/packages/server/src/repowise/server/schemas/pagination.py b/packages/server/src/repowise/server/schemas/pagination.py
new file mode 100644
index 000000000..6a760203b
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/pagination.py
@@ -0,0 +1,23 @@
+"""Pagination envelope shared across list endpoints."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class Paginated(BaseModel, Generic[T]):
+ """Stable envelope for paginated list endpoints.
+
+ Lets the UI show "Showing N of M / Load more" without guessing whether
+ a list was truncated by the server. `next_offset` is null when there
+ are no further pages.
+ """
+
+ items: list[T]
+ total: int
+ has_more: bool
+ next_offset: int | None = None
diff --git a/packages/server/src/repowise/server/schemas/repository.py b/packages/server/src/repowise/server/schemas/repository.py
new file mode 100644
index 000000000..4403783bc
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/repository.py
@@ -0,0 +1,72 @@
+"""Repository request/response models."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, field_validator
+
+
+class RepoCreate(BaseModel):
+ name: str
+ local_path: str
+ url: str = ""
+ default_branch: str = "main"
+ settings: dict | None = None
+
+ @field_validator("local_path")
+ @classmethod
+ def validate_local_path(cls, v: str) -> str:
+ resolved = Path(v).resolve()
+ if ".." in Path(v).parts:
+ raise ValueError("local_path must not contain '..' segments")
+ if not resolved.is_dir():
+ raise ValueError(f"local_path does not exist or is not a directory: {resolved}")
+ if not (resolved / ".git").exists():
+ raise ValueError(f"local_path is not a git repository (no .git found): {resolved}")
+ return str(resolved)
+
+
+class RepoUpdate(BaseModel):
+ name: str | None = None
+ url: str | None = None
+ default_branch: str | None = None
+ settings: dict | None = None
+
+
+class RepoResponse(BaseModel):
+ id: str
+ name: str
+ url: str
+ local_path: str
+ default_branch: str
+ head_commit: str | None
+ settings: dict
+ created_at: datetime
+ updated_at: datetime
+ # Workspace context — populated when the server is running in
+ # workspace mode. ``status`` indicates whether the repo has been
+ # indexed yet; the web UI uses it to render "needs index" CTA cards
+ # instead of silently dropping unindexed workspace repos from the
+ # sidebar. Always ``None`` in single-repo mode.
+ workspace_alias: str | None = None
+ workspace_status: str | None = None
+ is_primary: bool | None = None
+ docs_enabled: bool | None = None
+ docs_skip_reason: str | None = None
+
+ @classmethod
+ def from_orm(cls, obj: object) -> RepoResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ name=obj.name, # type: ignore[attr-defined]
+ url=obj.url, # type: ignore[attr-defined]
+ local_path=obj.local_path, # type: ignore[attr-defined]
+ default_branch=obj.default_branch, # type: ignore[attr-defined]
+ head_commit=obj.head_commit, # type: ignore[attr-defined]
+ settings=json.loads(obj.settings_json), # type: ignore[attr-defined]
+ created_at=obj.created_at, # type: ignore[attr-defined]
+ updated_at=obj.updated_at, # type: ignore[attr-defined]
+ )
diff --git a/packages/server/src/repowise/server/schemas/search.py b/packages/server/src/repowise/server/schemas/search.py
new file mode 100644
index 000000000..29c67306f
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/search.py
@@ -0,0 +1,21 @@
+"""Search request/response models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SearchRequest(BaseModel):
+ query: str
+ search_type: str = "semantic"
+ limit: int = Field(default=10, ge=1, le=100)
+
+
+class SearchResultResponse(BaseModel):
+ page_id: str
+ title: str
+ page_type: str
+ target_path: str
+ score: float
+ snippet: str
+ search_type: str
diff --git a/packages/server/src/repowise/server/schemas/symbols.py b/packages/server/src/repowise/server/schemas/symbols.py
new file mode 100644
index 000000000..6e918719a
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/symbols.py
@@ -0,0 +1,65 @@
+"""Symbol response models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class SymbolImportanceComponents(BaseModel):
+ """Transparent breakdown of the composite importance score so the UI can
+ explain *why* a symbol ranks where it does. All fields are normalized to
+ [0, 1] except booleans."""
+
+ file_pagerank: float = 0.0
+ visibility_factor: float = 0.5
+ complexity_norm: float = 0.0
+ kind_boost: float = 1.0
+ is_entry_point: bool = False
+
+
+class SymbolResponse(BaseModel):
+ id: str
+ repository_id: str
+ file_path: str
+ symbol_id: str
+ name: str
+ qualified_name: str
+ kind: str
+ signature: str
+ start_line: int
+ end_line: int
+ docstring: str | None
+ visibility: str
+ is_async: bool
+ complexity_estimate: int
+ language: str
+ parent_name: str | None
+ # Importance signals (populated when the list endpoint joins GraphNode /
+ # GitMetadata; nullable so single-symbol lookups remain lightweight).
+ importance_score: float | None = None
+ importance_components: SymbolImportanceComponents | None = None
+ file_pagerank: float | None = None
+ is_entry_point: bool | None = None
+ file_churn_percentile: float | None = None
+ file_is_hotspot: bool | None = None
+
+ @classmethod
+ def from_orm(cls, obj: object) -> SymbolResponse:
+ return cls(
+ id=obj.id, # type: ignore[attr-defined]
+ repository_id=obj.repository_id, # type: ignore[attr-defined]
+ file_path=obj.file_path, # type: ignore[attr-defined]
+ symbol_id=obj.symbol_id, # type: ignore[attr-defined]
+ name=obj.name, # type: ignore[attr-defined]
+ qualified_name=obj.qualified_name, # type: ignore[attr-defined]
+ kind=obj.kind, # type: ignore[attr-defined]
+ signature=obj.signature, # type: ignore[attr-defined]
+ start_line=obj.start_line, # type: ignore[attr-defined]
+ end_line=obj.end_line, # type: ignore[attr-defined]
+ docstring=obj.docstring, # type: ignore[attr-defined]
+ visibility=obj.visibility, # type: ignore[attr-defined]
+ is_async=obj.is_async, # type: ignore[attr-defined]
+ complexity_estimate=obj.complexity_estimate, # type: ignore[attr-defined]
+ language=obj.language, # type: ignore[attr-defined]
+ parent_name=obj.parent_name, # type: ignore[attr-defined]
+ )
diff --git a/packages/server/src/repowise/server/schemas/ui_helpers.py b/packages/server/src/repowise/server/schemas/ui_helpers.py
new file mode 100644
index 000000000..7d107fe67
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/ui_helpers.py
@@ -0,0 +1,35 @@
+"""Small request/response helper models (webhooks, provider config, cost)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class WebhookResponse(BaseModel):
+ event_id: str
+ status: str = "accepted"
+
+
+class SetActiveProviderRequest(BaseModel):
+ provider: str
+ model: str | None = None
+
+
+class SetApiKeyRequest(BaseModel):
+ api_key: str
+
+
+class CostGroupResponse(BaseModel):
+ group: str
+ calls: int
+ input_tokens: int
+ output_tokens: int
+ cost_usd: float
+
+
+class CostSummaryResponse(BaseModel):
+ total_cost_usd: float
+ total_calls: int
+ total_input_tokens: int
+ total_output_tokens: int
+ since: str | None
diff --git a/packages/server/src/repowise/server/schemas/workspace.py b/packages/server/src/repowise/server/schemas/workspace.py
new file mode 100644
index 000000000..895056a06
--- /dev/null
+++ b/packages/server/src/repowise/server/schemas/workspace.py
@@ -0,0 +1,140 @@
+"""Workspace (multi-repo) request/response models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class WorkspaceRepoEntry(BaseModel):
+ alias: str
+ path: str
+ is_primary: bool = False
+ indexed_at: str | None = None
+ last_commit_at_index: str | None = None
+ # Per-repo stats (populated from each repo's wiki.db)
+ repo_id: str | None = None
+ file_count: int = 0
+ symbol_count: int = 0
+ page_count: int = 0
+ doc_coverage_pct: float = 0.0
+ hotspot_count: int = 0
+ # Lifecycle status — surfaced so the web UI can render "needs index"
+ # or "missing directory" affordances instead of silently dropping the
+ # repo from the sidebar.
+ # "indexed" — has .repowise/wiki.db with at least one Repository row
+ # "needs_index" — directory exists but no .repowise/wiki.db yet
+ # "missing_dir" — workspace config references a path that no longer exists
+ status: str = "indexed"
+ # Whether docs were generated for this repo. False means a user
+ # action ("repowise update --repo <alias> --docs") is required to
+ # populate the Docs/Overview tabs in the web UI.
+ docs_enabled: bool = True
+ # Optional skip reason captured in state.json — surfaced as a
+ # transparency hint when docs are disabled.
+ docs_skip_reason: str | None = None
+
+
+class WorkspaceCrossRepoSummary(BaseModel):
+ co_change_count: int = 0
+ package_dep_count: int = 0
+ top_connections: list[dict] = []
+
+
+class WorkspaceContractSummary(BaseModel):
+ total_contracts: int = 0
+ total_links: int = 0
+ by_type: dict[str, int] = {}
+
+
+class WorkspaceResponse(BaseModel):
+ is_workspace: bool
+ workspace_root: str | None = None
+ workspace_name: str | None = None
+ repos: list[WorkspaceRepoEntry] = []
+ default_repo: str | None = None
+ cross_repo_summary: WorkspaceCrossRepoSummary | None = None
+ contract_summary: WorkspaceContractSummary | None = None
+
+
+class WorkspaceSyncResult(BaseModel):
+ alias: str
+ job_id: str | None = None
+ repo_id: str | None = None
+ status: str # "accepted", "skipped", "error"
+ reason: str | None = None
+
+
+class WorkspaceSyncResponse(BaseModel):
+ results: list[WorkspaceSyncResult]
+ accepted: int = 0
+ skipped: int = 0
+ errors: int = 0
+
+
+class WorkspaceContractEntry(BaseModel):
+ contract_id: str
+ contract_type: str
+ role: str
+ repo: str
+ file_path: str
+ symbol_name: str
+ confidence: float
+ service: str | None = None
+
+
+class WorkspaceContractLinkEntry(BaseModel):
+ contract_id: str
+ contract_type: str
+ match_type: str
+ confidence: float
+ provider_repo: str
+ provider_file: str
+ provider_symbol: str
+ consumer_repo: str
+ consumer_file: str
+ consumer_symbol: str
+
+
+class WorkspaceContractsResponse(BaseModel):
+ contracts: list[WorkspaceContractEntry]
+ links: list[WorkspaceContractLinkEntry]
+ total_contracts: int
+ total_links: int
+ by_type: dict[str, int] = {}
+
+
+class WorkspaceCoChangeEntry(BaseModel):
+ source_repo: str
+ source_file: str
+ target_repo: str
+ target_file: str
+ strength: float
+ frequency: int
+ last_date: str
+
+
+class WorkspaceCoChangesResponse(BaseModel):
+ co_changes: list[WorkspaceCoChangeEntry]
+ total: int
+
+
+class WorkspaceGraphNode(BaseModel):
+ repo_id: str
+ name: str
+ file_count: int = 0
+ coverage_pct: float = 0.0
+ health_score: int = 0
+ top_language: str = "unknown"
+
+
+class WorkspaceGraphEdge(BaseModel):
+ source: str
+ target: str
+ type: str # "contract" or "co_change"
+ strength: float = 0.0
+ label: str | None = None
+
+
+class WorkspaceGraphResponse(BaseModel):
+ nodes: list[WorkspaceGraphNode] = []
+ edges: list[WorkspaceGraphEdge] = []
diff --git a/tests/unit/server/test_schemas_package.py b/tests/unit/server/test_schemas_package.py
new file mode 100644
index 000000000..6300049a0
--- /dev/null
+++ b/tests/unit/server/test_schemas_package.py
@@ -0,0 +1,91 @@
+"""Characterization tests for the ``repowise.server.schemas`` package.
+
+These guard the split of the former single ``schemas.py`` module into a
+package: the public import surface must be unchanged, and the deduplicated
+graph-node models must serialize identically to their pre-split form
+(same field set, order, and JSON output).
+"""
+
+from __future__ import annotations
+
+from repowise.server import schemas
+
+
+def test_facade_reexports_every_model() -> None:
+ """Every name in ``__all__`` resolves to a class on the package."""
+ assert schemas.__all__, "__all__ must not be empty"
+ for name in schemas.__all__:
+ assert hasattr(schemas, name), f"{name} missing from schemas facade"
+
+
+# The three graph-node response models historically duplicated the same 16
+# fields verbatim; the split collapses that via inheritance. Field order is
+# part of the serialized contract, so pin it explicitly.
+_BASE_NODE_FIELDS = [
+ "node_id",
+ "node_type",
+ "language",
+ "symbol_count",
+ "pagerank",
+ "betweenness",
+ "community_id",
+ "is_test",
+ "is_entry_point",
+ "has_doc",
+ "is_hotspot",
+ "churn_percentile",
+ "is_dead",
+ "dead_confidence",
+ "has_decision",
+ "primary_owner",
+]
+
+
+def test_graph_node_field_order_preserved() -> None:
+ assert list(schemas.GraphNodeResponse.model_fields) == _BASE_NODE_FIELDS
+ assert list(schemas.DeadCodeGraphNodeResponse.model_fields) == [
+ *_BASE_NODE_FIELDS,
+ "confidence_group",
+ ]
+ assert list(schemas.HotFilesNodeResponse.model_fields) == [
+ *_BASE_NODE_FIELDS,
+ "commit_count",
+ ]
+
+
+def test_graph_node_serialization_unchanged() -> None:
+ base_kwargs = dict(
+ node_id="pkg/mod.py",
+ node_type="file",
+ language="python",
+ symbol_count=3,
+ pagerank=0.5,
+ betweenness=0.1,
+ community_id=2,
+ )
+ expected_base = {
+ "node_id": "pkg/mod.py",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 3,
+ "pagerank": 0.5,
+ "betweenness": 0.1,
+ "community_id": 2,
+ "is_test": False,
+ "is_entry_point": False,
+ "has_doc": False,
+ "is_hotspot": False,
+ "churn_percentile": None,
+ "is_dead": False,
+ "dead_confidence": None,
+ "has_decision": False,
+ "primary_owner": None,
+ }
+ assert schemas.GraphNodeResponse(**base_kwargs).model_dump() == expected_base
+ assert schemas.DeadCodeGraphNodeResponse(
+ **base_kwargs, confidence_group="certain"
+ ).model_dump() == {**expected_base, "confidence_group": "certain"}
+ assert schemas.HotFilesNodeResponse(**base_kwargs, commit_count=7).model_dump() == {
+ **expected_base,
+ "commit_count": 7,
+ }