paperfigg 0.2.6__tar.gz

paperfigg-0.2.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paperfig contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paperfigg-0.2.6/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: paperfigg
+Version: 0.2.6
+Summary: Agentic CLI for generating academic figures from research papers
+Author: paperfig contributors
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: cli
+Requires-Dist: typer>=0.9.0; extra == "cli"
+Requires-Dist: rich>=13.7.0; extra == "cli"
+Provides-Extra: png
+Requires-Dist: cairosvg>=2.7.0; extra == "png"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Provides-Extra: pdf
+Requires-Dist: pdfminer.six>=20221105; extra == "pdf"
+Requires-Dist: pypdf>=3.0.0; extra == "pdf"
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7.0; extra == "svg"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0.0; extra == "yaml"
+Dynamic: license-file
+
+# paperfig
+[![CI](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/ci.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/ci.yml)
+[![Docs Drift](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/docs-drift.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/docs-drift.yml)
+[![Publish](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/publish.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/publish.yml)
+
+`paperfig` is a production-grade CLI that converts research papers (PDF or Markdown) into publication-ready academic figures using an agentic planning -> generation -> critique pipeline.
+
+The core differentiator is that agent reasoning and architecture decisions are stored as versioned repo artifacts (architecture docs, flows, Mermaid diagrams, templates, audits) so humans and agents can evolve the system together.
+
+## Install
+- Standard CLI + PNG export:
+  - `pip install "paperfigg[cli,png]"`
+- Developer tooling:
+  - `pip install "paperfigg[cli,png,dev,yaml,pdf,mcp]"`
+- CLI-first local install:
+  - `pipx install .`
+  - `uv tool install .`
+  - Published package name is `paperfigg`; CLI command remains `paperfig`.
+
+## Quickstart (Mock Mode, No Keys)
+Mock mode is designed for instant local runs and realistic output artifacts.
+
+```bash
+pip install "paperfigg[cli,png]"
+paperfig doctor
+paperfig generate examples/sample_paper.md --mode mock
+paperfig docs check
+```
+
+## 1-Minute Demo
+```bash
+pip install "paperfigg[cli,png]"
+paperfig doctor
+paperfig generate examples/sample_paper.md --mode mock
+ls runs/*/figures/*/final/figure.svg
+```
+
+## Full Mode (PaperBanana MCP)
+Use full mode when you want real PaperBanana generation via MCP.
+
+```bash
+pip install "paperfigg[cli,png,mcp]"
+export PAPERFIG_MCP_SERVER=paperbanana
+export PAPERFIG_MCP_COMMAND="python -m your_mcp_server"
+paperfig doctor --probe-mcp
+paperfig generate examples/sample_paper.md --mode real
+```
+
+## What You Get
+- Generated figures (SVG and optional transparent PNG)
+- LaTeX include snippets
+- Captions and figure plans
+- Traceability mapping from figure elements to source text spans
+- Governance artifacts (`docs_drift_report.json`, `architecture_critique.json`, `repro_audit.json`)
+
+Sample proof assets are committed in `docs/gallery/sample_paper`:
+- `docs/gallery/sample_paper/fig-21a078a0.svg`
+- `docs/gallery/sample_paper/plan.json`
+- `docs/gallery/sample_paper/repro_audit.json`
+- `docs/gallery/sample_paper/architecture_critique.json`
+
+![Sample methodology figure](docs/gallery/sample_paper/fig-21a078a0.svg)
+
+## What It Does
+- Parses papers and extracts methodology, system description, and results sections.
+- Plans figures through reusable flow templates and fallback heuristics.
+- Generates figures via PaperBanana MCP and iterates with critique feedback loops.
+- Regenerates docs and gates on drift for architecture governance.
+- Runs reproducibility audits and architecture critiques as first-class run artifacts.
+- Provides a constrained autonomous lab scaffold for iterative research experiments.
+
+## How The Agentic System Works
+The system uses specialized agents:
+- `PlannerAgent` chooses figures and template-aligned abstractions.
+- `GeneratorAgent` calls PaperBanana via MCP and emits traceable figure elements.
+- `CriticAgent` scores faithfulness, readability, conciseness, and aesthetics.
+- `ArchitectureCriticAgent` audits run-level architecture quality and governance completeness.
+
+Full architecture documentation and flow diagrams live in `docs/architecture`.
+
+## CLI Usage
+<!-- AUTO-GEN:START cli-command-catalog -->
+- `paperfig generate`
+- `paperfig critique`
+- `paperfig export`
+- `paperfig doctor`
+- `paperfig inspect`
+- `paperfig docs regenerate`
+- `paperfig docs check`
+- `paperfig templates list`
+- `paperfig templates validate`
+- `paperfig critique-architecture`
+- `paperfig audit`
+- `paperfig lab init`
+- `paperfig lab propose`
+- `paperfig lab run`
+- `paperfig lab review`
+- `paperfig lab status`
+<!-- AUTO-GEN:END cli-command-catalog -->
+
+## Flow Template Pack
+<!-- AUTO-GEN:START flow-template-catalog -->
+- `ablation_matrix` (ablation)
+- `dataset_characteristics` (dataset_overview)
+- `error_analysis_breakdown` (error_analysis)
+- `limitations_threats_to_validity` (limitations)
+- `methodology_pipeline` (methodology)
+- `results_summary_plot` (results_plot)
+- `system_overview` (system_overview)
+- `training_compute_profile` (compute_profile)
+<!-- AUTO-GEN:END flow-template-catalog -->
+
+## Outputs
+Each run creates a `runs/<run_id>/` workspace containing:
+- `figures/<figure_id>/figure.svg`
+- `figures/<figure_id>/traceability.json`
+- `captions.txt`
+- `inspect.json`
+- `docs_drift_report.json`
+- `architecture_critique.json`
+- `repro_audit.json`
+- `exports/` with PNG, SVG, LaTeX snippets, and `export_report.json`
+
+## Configuration
+Default config lives in `paperfig.yaml`:
+- docs scope and manifest path (`docs/docs_manifest.yaml`)
+- architecture critique mode and severity gate
+- reproducibility audit mode (`soft` by default)
+- template pack (`expanded_v1`)
+- lab registry path and sandbox policy (`config/lab_policy.yaml`)
+
+## Verification
+- Run unit/integration tests: `python3 -m unittest discover -s tests -v`
+- Run docs drift check: `./scripts/check_docs_drift.sh`
+- Run full quality checks: `./scripts/check_quality.sh`
+
+## CI
+- GitHub Actions pipeline: `.github/workflows/ci.yml`
+- GitHub Actions docs drift gate: `.github/workflows/docs-drift.yml`
+- GitHub Actions PyPI publish: `.github/workflows/publish.yml`
+- Publish workflow expects `PYPI_API_TOKEN` secret in GitHub environment `pypi`.
+- Manual `publish.yml` runs are dry-run by default; set workflow input `publish=true` to actually upload.
+- GitLab pipeline: `.gitlab-ci.yml`
+- All wrappers call shared scripts in `scripts/` (no duplicated CI logic in YAML)
+
+## Community
+- Changelog: `CHANGELOG.md`
+- Contributing: `CONTRIBUTING.md`
+- Code of conduct: `CODE_OF_CONDUCT.md`
+- Citation metadata: `CITATION.cff`
+
+## Architecture Docs
+See:
+- `docs/architecture/AI-Architecture-Analysis.md`
+- `docs/architecture/flows/index.md`

paperfigg-0.2.6/README.md

@@ -0,0 +1,155 @@
+# paperfig
+[![CI](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/ci.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/ci.yml)
+[![Docs Drift](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/docs-drift.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/docs-drift.yml)
+[![Publish](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/publish.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfig/actions/workflows/publish.yml)
+
+`paperfig` is a production-grade CLI that converts research papers (PDF or Markdown) into publication-ready academic figures using an agentic planning -> generation -> critique pipeline.
+
+The core differentiator is that agent reasoning and architecture decisions are stored as versioned repo artifacts (architecture docs, flows, Mermaid diagrams, templates, audits) so humans and agents can evolve the system together.
+
+## Install
+- Standard CLI + PNG export:
+  - `pip install "paperfigg[cli,png]"`
+- Developer tooling:
+  - `pip install "paperfigg[cli,png,dev,yaml,pdf,mcp]"`
+- CLI-first local install:
+  - `pipx install .`
+  - `uv tool install .`
+  - Published package name is `paperfigg`; CLI command remains `paperfig`.
+
+## Quickstart (Mock Mode, No Keys)
+Mock mode is designed for instant local runs and realistic output artifacts.
+
+```bash
+pip install "paperfigg[cli,png]"
+paperfig doctor
+paperfig generate examples/sample_paper.md --mode mock
+paperfig docs check
+```
+
+## 1-Minute Demo
+```bash
+pip install "paperfigg[cli,png]"
+paperfig doctor
+paperfig generate examples/sample_paper.md --mode mock
+ls runs/*/figures/*/final/figure.svg
+```
+
+## Full Mode (PaperBanana MCP)
+Use full mode when you want real PaperBanana generation via MCP.
+
+```bash
+pip install "paperfigg[cli,png,mcp]"
+export PAPERFIG_MCP_SERVER=paperbanana
+export PAPERFIG_MCP_COMMAND="python -m your_mcp_server"
+paperfig doctor --probe-mcp
+paperfig generate examples/sample_paper.md --mode real
+```
+
+## What You Get
+- Generated figures (SVG and optional transparent PNG)
+- LaTeX include snippets
+- Captions and figure plans
+- Traceability mapping from figure elements to source text spans
+- Governance artifacts (`docs_drift_report.json`, `architecture_critique.json`, `repro_audit.json`)
+
+Sample proof assets are committed in `docs/gallery/sample_paper`:
+- `docs/gallery/sample_paper/fig-21a078a0.svg`
+- `docs/gallery/sample_paper/plan.json`
+- `docs/gallery/sample_paper/repro_audit.json`
+- `docs/gallery/sample_paper/architecture_critique.json`
+
+![Sample methodology figure](docs/gallery/sample_paper/fig-21a078a0.svg)
+
+## What It Does
+- Parses papers and extracts methodology, system description, and results sections.
+- Plans figures through reusable flow templates and fallback heuristics.
+- Generates figures via PaperBanana MCP and iterates with critique feedback loops.
+- Regenerates docs and gates on drift for architecture governance.
+- Runs reproducibility audits and architecture critiques as first-class run artifacts.
+- Provides a constrained autonomous lab scaffold for iterative research experiments.
+
+## How The Agentic System Works
+The system uses specialized agents:
+- `PlannerAgent` chooses figures and template-aligned abstractions.
+- `GeneratorAgent` calls PaperBanana via MCP and emits traceable figure elements.
+- `CriticAgent` scores faithfulness, readability, conciseness, and aesthetics.
+- `ArchitectureCriticAgent` audits run-level architecture quality and governance completeness.
+
+Full architecture documentation and flow diagrams live in `docs/architecture`.
+
+## CLI Usage
+<!-- AUTO-GEN:START cli-command-catalog -->
+- `paperfig generate`
+- `paperfig critique`
+- `paperfig export`
+- `paperfig doctor`
+- `paperfig inspect`
+- `paperfig docs regenerate`
+- `paperfig docs check`
+- `paperfig templates list`
+- `paperfig templates validate`
+- `paperfig critique-architecture`
+- `paperfig audit`
+- `paperfig lab init`
+- `paperfig lab propose`
+- `paperfig lab run`
+- `paperfig lab review`
+- `paperfig lab status`
+<!-- AUTO-GEN:END cli-command-catalog -->
+
+## Flow Template Pack
+<!-- AUTO-GEN:START flow-template-catalog -->
+- `ablation_matrix` (ablation)
+- `dataset_characteristics` (dataset_overview)
+- `error_analysis_breakdown` (error_analysis)
+- `limitations_threats_to_validity` (limitations)
+- `methodology_pipeline` (methodology)
+- `results_summary_plot` (results_plot)
+- `system_overview` (system_overview)
+- `training_compute_profile` (compute_profile)
+<!-- AUTO-GEN:END flow-template-catalog -->
+
+## Outputs
+Each run creates a `runs/<run_id>/` workspace containing:
+- `figures/<figure_id>/figure.svg`
+- `figures/<figure_id>/traceability.json`
+- `captions.txt`
+- `inspect.json`
+- `docs_drift_report.json`
+- `architecture_critique.json`
+- `repro_audit.json`
+- `exports/` with PNG, SVG, LaTeX snippets, and `export_report.json`
+
+## Configuration
+Default config lives in `paperfig.yaml`:
+- docs scope and manifest path (`docs/docs_manifest.yaml`)
+- architecture critique mode and severity gate
+- reproducibility audit mode (`soft` by default)
+- template pack (`expanded_v1`)
+- lab registry path and sandbox policy (`config/lab_policy.yaml`)
+
+## Verification
+- Run unit/integration tests: `python3 -m unittest discover -s tests -v`
+- Run docs drift check: `./scripts/check_docs_drift.sh`
+- Run full quality checks: `./scripts/check_quality.sh`
+
+## CI
+- GitHub Actions pipeline: `.github/workflows/ci.yml`
+- GitHub Actions docs drift gate: `.github/workflows/docs-drift.yml`
+- GitHub Actions PyPI publish: `.github/workflows/publish.yml`
+- Publish workflow expects `PYPI_API_TOKEN` secret in GitHub environment `pypi`.
+- Manual `publish.yml` runs are dry-run by default; set workflow input `publish=true` to actually upload.
+- GitLab pipeline: `.gitlab-ci.yml`
+- All wrappers call shared scripts in `scripts/` (no duplicated CI logic in YAML)
+
+## Community
+- Changelog: `CHANGELOG.md`
+- Contributing: `CONTRIBUTING.md`
+- Code of conduct: `CODE_OF_CONDUCT.md`
+- Citation metadata: `CITATION.cff`
+
+## Architecture Docs
+See:
+- `docs/architecture/AI-Architecture-Analysis.md`
+- `docs/architecture/flows/index.md`

paperfigg-0.2.6/paperfig/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.2.6"

paperfigg-0.2.6/paperfig/agents/__init__.py

@@ -0,0 +1 @@
+__all__ = ["planner", "generator", "critic", "architecture_critic"]

paperfigg-0.2.6/paperfig/agents/architecture_critic.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Dict, List
+
+from paperfig.utils.prompts import load_prompt
+from paperfig.utils.types import ArchitectureCritiqueFinding, ArchitectureCritiqueReport
+
+
+SEVERITY_ORDER = {
+    "info": 0,
+    "minor": 1,
+    "major": 2,
+    "critical": 3,
+}
+
+
+class ArchitectureCriticAgent:
+    def __init__(self) -> None:
+        self.prompt = load_prompt("critique_architecture.txt")
+
+    def critique(self, run_dir: Path, block_severity: str = "critical") -> ArchitectureCritiqueReport:
+        run_id = run_dir.name
+        findings: List[ArchitectureCritiqueFinding] = []
+
+        inspect_path = run_dir / "inspect.json"
+        if not inspect_path.exists():
+            findings.append(
+                ArchitectureCritiqueFinding(
+                    finding_id="missing_inspect",
+                    severity="major",
+                    title="Missing inspect summary",
+                    description="Run is missing inspect.json, limiting architecture observability.",
+                    evidence=str(inspect_path),
+                    suggestion="Regenerate inspect summary via pipeline finalization or `paperfig inspect`.",
+                )
+            )
+        else:
+            inspect_data = json.loads(inspect_path.read_text(encoding="utf-8"))
+            failed = inspect_data.get("aggregate", {}).get("failed_count", 0)
+            if isinstance(failed, int) and failed > 0:
+                findings.append(
+                    ArchitectureCritiqueFinding(
+                        finding_id="failed_figures",
+                        severity="major",
+                        title="Failed figures present",
+                        description="At least one figure did not pass final critique.",
+                        evidence=f"failed_count={failed}",
+                        suggestion="Review failed figures and rerun with improved prompts/templates.",
+                    )
+                )
+
+            avg_cov = inspect_data.get("aggregate", {}).get("avg_traceability_coverage")
+            if isinstance(avg_cov, (int, float)) and avg_cov < 0.8:
+                findings.append(
+                    ArchitectureCritiqueFinding(
+                        finding_id="traceability_coverage_low",
+                        severity="major",
+                        title="Low traceability coverage",
+                        description="Average traceability coverage is below recommended threshold.",
+                        evidence=f"avg_traceability_coverage={avg_cov}",
+                        suggestion="Ensure all figure elements include source span mappings.",
+                    )
+                )
+
+        plan_path = run_dir / "plan.json"
+        if not plan_path.exists():
+            findings.append(
+                ArchitectureCritiqueFinding(
+                    finding_id="missing_plan",
+                    severity="critical",
+                    title="Missing plan artifact",
+                    description="Run is missing plan.json.",
+                    evidence=str(plan_path),
+                    suggestion="Investigate planner stage and regenerate run artifacts.",
+                )
+            )
+        else:
+            plan_data = json.loads(plan_path.read_text(encoding="utf-8"))
+            if isinstance(plan_data, list) and not plan_data:
+                findings.append(
+                    ArchitectureCritiqueFinding(
+                        finding_id="empty_plan",
+                        severity="critical",
+                        title="Empty figure plan",
+                        description="Planner generated no figures for this run.",
+                        evidence="plan.json contains 0 entries",
+                        suggestion="Review section extraction and template trigger rules.",
+                    )
+                )
+
+        docs_report_path = run_dir / "docs_drift_report.json"
+        if not docs_report_path.exists():
+            findings.append(
+                ArchitectureCritiqueFinding(
+                    finding_id="missing_docs_drift_report",
+                    severity="minor",
+                    title="Missing docs drift report",
+                    description="No docs_drift_report.json was found for this run.",
+                    evidence=str(docs_report_path),
+                    suggestion="Enable docs check in the generation finalization stage.",
+                )
+            )
+
+        max_seen = max((SEVERITY_ORDER.get(item.severity, 0) for item in findings), default=0)
+        blocked = max_seen >= SEVERITY_ORDER.get(block_severity, SEVERITY_ORDER["critical"])
+
+        summary = "No architecture findings."
+        if findings:
+            summary = f"{len(findings)} finding(s); highest severity={self._severity_name(max_seen)}"
+
+        return ArchitectureCritiqueReport(
+            run_id=run_id,
+            block_severity=block_severity,
+            findings=findings,
+            blocked=blocked,
+            summary=summary,
+            generated_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        )
+
+    @staticmethod
+    def _severity_name(value: int) -> str:
+        for name, rank in SEVERITY_ORDER.items():
+            if rank == value:
+                return name
+        return "info"
+
+
+def report_to_dict(report: ArchitectureCritiqueReport) -> Dict[str, object]:
+    return asdict(report)

paperfigg-0.2.6/paperfig/agents/critic.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List
+
+from paperfig.utils.prompts import load_prompt
+from paperfig.utils.types import CritiqueReport, FigurePlan, PaperContent
+
+
+class CriticAgent:
+    def __init__(self, threshold: float = 0.75, dimension_threshold: float = 0.55) -> None:
+        self.threshold = threshold
+        self.dimension_threshold = dimension_threshold
+        self.prompt = load_prompt("critique_figure.txt")
+
+    def critique(self, svg_path: Path, plan: FigurePlan, paper: PaperContent) -> CritiqueReport:
+        svg_text = svg_path.read_text(encoding="utf-8")
+        issues: List[str] = []
+        recommendations: List[str] = []
+        dimensions = self._score_dimensions(svg_text, plan, paper)
+        score = sum(dimensions.values()) / len(dimensions)
+        failed_dimensions = [name for name, value in dimensions.items() if value < self.dimension_threshold]
+
+        if "readability" in failed_dimensions:
+            issues.append("Readability below threshold: labels or visual structure are insufficient.")
+            recommendations.append("Add clear labels, improve hierarchy, and avoid dense overlaps.")
+        if "faithfulness" in failed_dimensions:
+            issues.append("Faithfulness below threshold: figure support from source spans is weak.")
+            recommendations.append("Tie every key label and relation to explicit source text spans.")
+        if "conciseness" in failed_dimensions:
+            issues.append("Conciseness below threshold: figure is either too sparse or overloaded.")
+            recommendations.append("Keep only essential elements and remove decorative clutter.")
+        if "aesthetics" in failed_dimensions:
+            issues.append("Aesthetics below threshold: layout balance and presentation need refinement.")
+            recommendations.append("Improve alignment, spacing, and consistent visual encoding.")
+
+        passed = (
+            score >= self.threshold
+            and not failed_dimensions
+            and not any("invalid" in issue.lower() for issue in issues)
+        )
+
+        if not passed:
+            recommendations.append("Revise layout to improve clarity and alignment with the paper.")
+
+        return CritiqueReport(
+            figure_id=plan.figure_id,
+            score=round(min(score, 1.0), 3),
+            threshold=self.threshold,
+            quality_dimensions={k: round(v, 3) for k, v in dimensions.items()},
+            dimension_threshold=self.dimension_threshold,
+            failed_dimensions=failed_dimensions,
+            issues=issues,
+            recommendations=recommendations,
+            passed=passed,
+        )
+
+    def _score_dimensions(
+        self,
+        svg_text: str,
+        plan: FigurePlan,
+        paper: PaperContent,
+    ) -> Dict[str, float]:
+        return {
+            "faithfulness": self._score_faithfulness(svg_text, plan, paper),
+            "readability": self._score_readability(svg_text),
+            "conciseness": self._score_conciseness(svg_text),
+            "aesthetics": self._score_aesthetics(svg_text),
+        }
+
+    def _score_faithfulness(self, svg_text: str, plan: FigurePlan, paper: PaperContent) -> float:
+        score = 0.35
+        if plan.source_spans:
+            score += 0.3
+        if len(plan.description.strip()) > 20:
+            score += 0.1
+        if plan.kind == "results_plot" and paper.sections.get("results") and paper.sections["results"].text:
+            score += 0.15
+        if "mock paperbanana output" in svg_text.lower():
+            score += 0.05
+        return min(score, 1.0)
+
+    def _score_readability(self, svg_text: str) -> float:
+        score = 0.3
+        text_count = svg_text.count("<text")
+        if text_count >= 2:
+            score += 0.25
+        elif text_count == 1:
+            score += 0.15
+        if any(tag in svg_text for tag in ("<rect", "<path", "<line", "<circle")):
+            score += 0.2
+        if "font-size" in svg_text:
+            score += 0.1
+        if "viewBox" in svg_text:
+            score += 0.1
+        return min(score, 1.0)
+
+    def _score_conciseness(self, svg_text: str) -> float:
+        score = 0.5
+        length = len(svg_text)
+        if 250 <= length <= 9000:
+            score += 0.25
+        elif length > 12000:
+            score -= 0.2
+        else:
+            score -= 0.1
+        primitive_count = sum(svg_text.count(tag) for tag in ("<rect", "<path", "<line", "<circle", "<polygon"))
+        if 1 <= primitive_count <= 40:
+            score += 0.2
+        elif primitive_count > 120:
+            score -= 0.2
+        return max(min(score, 1.0), 0.0)
+
+    def _score_aesthetics(self, svg_text: str) -> float:
+        score = 0.35
+        if "viewBox" in svg_text and "width" in svg_text and "height" in svg_text:
+            score += 0.2
+        if "stroke" in svg_text:
+            score += 0.15
+        if "fill" in svg_text:
+            score += 0.15
+        if "font-family" in svg_text:
+            score += 0.1
+        return min(score, 1.0)