archy_trend

Instructions

Implementation Reference

• src/archy/mcp.py:369-378 (registration)

  Tool registration for 'archy_trend' via @server.tool decorator. Delegates to _run_trend().

  @server.tool(
      name="archy_trend",
      description=(
          "Read the recent score history (.archy/history.jsonl) for a Python "
          "project. Returns up to last_n rows ordered oldest-first so an agent "
          "can compare deltas."
      ),
  )
  def archy_trend(path: str, last_n: int = 10) -> list[TrendRow]:
      return _run_trend(Path(path), last_n=last_n)

• src/archy/mcp.py:668-693 (handler)

  _run_trend() is the handler that reads history from .archy/history.jsonl and transforms HistoryRow objects into TrendRow response model instances.

  def _run_trend(path: Path, *, last_n: int) -> list[TrendRow]:
      rows = read_history(path / ".archy" / "history.jsonl")
      window = rows[-last_n:] if last_n > 0 else rows
      return [
          TrendRow(
              timestamp=r.timestamp,
              commit=r.commit,
              branch=r.branch,
              score=TrendRowScore(
                  overall=r.overall,
                  modularity=r.modularity,
                  acyclicity=r.acyclicity,
                  depth=r.depth,
                  equality=r.equality,
              ),
              inputs=TrendRowInputs(
                  module_count=r.module_count,
                  edge_count=r.edge_count,
                  cycle_count=r.cycle_count,
                  tangle_ratio=r.tangle_ratio,
                  max_depth=r.max_depth,
                  community_count=r.community_count,
              ),
          )
          for r in window
      ]

• src/archy/mcp.py:159-188 (schema)

  TrendRowScore, TrendRowInputs, and TrendRow Pydantic models define the output schema for the archy_trend tool.

  class TrendRowScore(BaseModel):
      model_config = ConfigDict(frozen=True)
  
      overall: float
      modularity: float
      acyclicity: float
      depth: float
      equality: float
  
  
  class TrendRowInputs(BaseModel):
      model_config = ConfigDict(frozen=True)
  
      module_count: int
      edge_count: int
      cycle_count: int
      tangle_ratio: float
      max_depth: int
      community_count: int
  
  
  class TrendRow(BaseModel):
      model_config = ConfigDict(frozen=True)
  
      timestamp: str
      commit: str | None
      branch: str | None
      score: TrendRowScore
      inputs: TrendRowInputs

• src/archy/history.py:46-63 (helper)

  read_history() (imported as read_history) reads .archy/history.jsonl and parses JSONL lines into HistoryRow objects.

  def read(history_path: Path) -> list[HistoryRow]:
      if not history_path.exists():
          return []
      rows: list[HistoryRow] = []
      for raw_line in history_path.read_text(encoding="utf-8").splitlines():
          line = raw_line.strip()
          if not line:
              continue
          try:
              data = json.loads(line)
          except json.JSONDecodeError:
              # Malformed lines skipped rather than aborted; the file is
              # append-only and a half-flushed write should not break trend.
              continue
          row = _row_from_dict(data)
          if row is not None:
              rows.append(row)
      return rows

• src/archy/history.py:20-36 (helper)

  HistoryRow Pydantic model - the raw history data format stored in .archy/history.jsonl.

  class HistoryRow(BaseModel):
      model_config = ConfigDict(frozen=True)
  
      timestamp: str  # ISO-8601 UTC, second precision, suffixed Z.
      commit: str | None
      branch: str | None
      overall: float
      modularity: float
      acyclicity: float
      depth: float
      equality: float
      module_count: int
      edge_count: int
      cycle_count: int
      tangle_ratio: float
      max_depth: int
      community_count: int