utopia-analyzer 1.0.0__py3-none-any.whl

utopia/__init__.py

@@ -0,0 +1,3 @@
+"""UTOPIA: Ultimate Technical Overview & Portfolio Intelligence Analyzer."""
+
+__version__ = "1.0.0"

utopia/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running UTOPIA as a module: python -m utopia <username>."""
+
+from utopia.cli import main
+
+if __name__ == "__main__":
+    main()

utopia/archetypes.py

@@ -0,0 +1,168 @@
+"""Developer archetype detection based on languages, topics, and repo signals."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Callable
+
+from utopia.github_client import ProfileData, RepoData
+
+
+# ---------------------------------------------------------------------------
+# Archetype signal definitions
+# ---------------------------------------------------------------------------
+ARCHETYPE_LANGUAGES: dict[str, set[str]] = {
+    "backend": {"python", "go", "java", "rust", "ruby", "php", "c#", "c++", "c"},
+    "frontend": {"javascript", "typescript", "html", "css"},
+    "mobile": {"swift", "kotlin", "dart", "java", "objective-c"},
+    "ai_ml": {"python", "r", "julia"},
+    "data": {"python", "sql", "scala", "r"},
+    "devops": {"dockerfile", "shell", "powershell", "go", "yaml"},
+}
+
+ARCHETYPE_TOPICS: dict[str, set[str]] = {
+    "backend": {"api", "backend", "database", "server", "rest", "graphql", "microservices"},
+    "frontend": {"react", "vue", "angular", "css", "ui", "frontend", "webpack", "nextjs"},
+    "mobile": {"android", "ios", "flutter", "react-native", "mobile", "swiftui"},
+    "ai_ml": {
+        "tensorflow",
+        "pytorch",
+        "machine-learning",
+        "ai",
+        "deep-learning",
+        "nlp",
+        "llm",
+        "neural-network",
+    },
+    "data": {"data", "etl", "pipeline", "spark", "kafka", "hadoop", "airflow", "dbt"},
+    "devops": {"docker", "kubernetes", "terraform", "ci-cd", "github-actions", "ansible"},
+}
+
+ARCHETYPE_LABELS = {
+    "backend": "Backend Engineer",
+    "frontend": "Frontend Engineer",
+    "full_stack": "Full Stack Developer",
+    "mobile": "Mobile Developer",
+    "ai_ml": "AI/ML Developer",
+    "data": "Data Engineer",
+    "devops": "DevOps Engineer",
+}
+
+# Thresholds used to convert raw signal counts into percentage scores.
+ARCHETYPE_IDEAL_LANGUAGE_BYTES = 1_000_000  # ~1 MB of archetype-aligned code
+ARCHETYPE_IDEAL_TOPIC_MATCHES = 5
+ARCHETYPE_IDEAL_REPO_SIGNALS = 3  # e.g. workflow + dockerfile + topic matches
+
+
+# ---------------------------------------------------------------------------
+# Signal aggregation
+# ---------------------------------------------------------------------------
+def _collect_signals(profile: ProfileData) -> dict[str, dict[str, float]]:
+    """Aggregate raw signals per archetype across all repos."""
+    signals: dict[str, dict[str, float]] = {
+        key: {"language_bytes": 0.0, "topic_matches": 0.0, "repo_signals": 0.0}
+        for key in ARCHETYPE_LABELS
+        if key != "full_stack"
+    }
+
+    for repo in profile.repos:
+        repo_topics = {t.lower() for t in repo.topics}
+        repo_main_lang = (repo.language or "").lower()
+
+        for archetype in signals:
+            # Language bytes
+            if repo_main_lang in ARCHETYPE_LANGUAGES.get(archetype, set()):
+                signals[archetype]["language_bytes"] += 1.0  # count repos, not bytes
+            for lang, bytes_count in repo.languages.items():
+                if lang.lower() in ARCHETYPE_LANGUAGES.get(archetype, set()):
+                    signals[archetype]["language_bytes"] += bytes_count
+
+            # Topic matches
+            matching_topics = repo_topics & ARCHETYPE_TOPICS.get(archetype, set())
+            signals[archetype]["topic_matches"] += len(matching_topics)
+
+            # Repo-level file/topic signals
+            repo_signal = 0.0
+            if archetype == "devops":
+                if repo.has_workflows:
+                    repo_signal += 1.0
+                if repo.has_dockerfile:
+                    repo_signal += 1.0
+                if repo_topics & ARCHETYPE_TOPICS["devops"]:
+                    repo_signal += 1.0
+            else:
+                if repo_main_lang in ARCHETYPE_LANGUAGES.get(archetype, set()):
+                    repo_signal += 0.5
+                if matching_topics:
+                    repo_signal += 0.5
+            signals[archetype]["repo_signals"] += repo_signal
+
+    return signals
+
+
+def _normalize(value: float, ideal: float) -> float:
+    if ideal <= 0:
+        return 0.0
+    return min(value / ideal, 1.0)
+
+
+def _log_normalize(value: float, ideal: float) -> float:
+    if value <= 0 or ideal <= 0:
+        return 0.0
+    return min(math.log10(value) / math.log10(ideal), 1.0)
+
+
+def _archetype_percentage(raw_signals: dict[str, float]) -> float:
+    """Convert raw signals into a 0-100 percentage score."""
+    language_part = _log_normalize(
+        raw_signals["language_bytes"], ARCHETYPE_IDEAL_LANGUAGE_BYTES
+    )
+    topic_part = _normalize(raw_signals["topic_matches"], ARCHETYPE_IDEAL_TOPIC_MATCHES)
+    repo_part = _normalize(raw_signals["repo_signals"], ARCHETYPE_IDEAL_REPO_SIGNALS)
+
+    # Weighted blend: languages are the strongest signal, topics second, repo files third.
+    blended = language_part * 0.5 + topic_part * 0.3 + repo_part * 0.2
+    return round(blended * 100, 1)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+@dataclass
+class ArchetypeResult:
+    key: str
+    label: str
+    percentage: float
+
+
+def detect_archetypes(profile: ProfileData) -> list[ArchetypeResult]:
+    """Detect and rank developer archetypes for the given profile."""
+    raw = _collect_signals(profile)
+
+    base_scores: dict[str, float] = {}
+    for key, sigs in raw.items():
+        base_scores[key] = _archetype_percentage(sigs)
+
+    # Full stack is derived from backend + frontend balance.
+    backend = base_scores.get("backend", 0)
+    frontend = base_scores.get("frontend", 0)
+    if backend > 0 and frontend > 0:
+        base_scores["full_stack"] = round((min(backend, frontend) * 0.6 + max(backend, frontend) * 0.2), 1)
+    else:
+        base_scores["full_stack"] = 0.0
+
+    results = [
+        ArchetypeResult(key=key, label=ARCHETYPE_LABELS[key], percentage=score)
+        for key, score in base_scores.items()
+    ]
+    results.sort(key=lambda r: r.percentage, reverse=True)
+    return results
+
+
+def top_archetypes(
+    profile: ProfileData, n: int = 4, min_percentage: float = 3.0
+) -> list[ArchetypeResult]:
+    """Return the top N archetypes, filtering out negligible matches."""
+    all_archetypes = detect_archetypes(profile)
+    return [a for a in all_archetypes if a.percentage >= min_percentage][:n]

utopia/cli.py

@@ -0,0 +1,107 @@
+"""CLI entry point for UTOPIA."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Ensure UTF-8 output on Windows terminals so Unicode bar charts render correctly.
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+import click
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from utopia.formatters import json_output, markdown_output, terminal
+from utopia.github_client import (
+    GitHubError,
+    RateLimitError,
+    UserNotFoundError,
+    fetch_profile,
+)
+from utopia.report import build_report
+
+
+load_dotenv()
+
+
+@click.command()
+@click.argument("username")
+@click.option("--token", default=None, help="GitHub Personal Access Token for higher rate limits.")
+@click.option(
+    "--output",
+    "output_format",
+    type=click.Choice(["terminal", "json", "markdown"], case_sensitive=False),
+    default="terminal",
+    help="Output format (default: terminal).",
+)
+@click.option("--save", "save_path", default=None, help="File path to save the report.")
+@click.option("--roast", is_flag=True, help="Enable Portfolio Roast Mode.")
+@click.option("--no-color", is_flag=True, help="Disable colored terminal output.")
+@click.option("--no-cache", is_flag=True, help="Skip cached data and refresh from GitHub.")
+def main(
+    username: str,
+    token: str | None,
+    output_format: str,
+    save_path: str | None,
+    roast: bool,
+    no_color: bool,
+    no_cache: bool,
+) -> None:
+    """Analyze a GitHub profile and generate a UTOPIA portfolio report."""
+    token = token or os.getenv("GITHUB_TOKEN")
+    output_format = output_format.lower()
+
+    console = Console(no_color=no_color)
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+            transient=True,
+        ) as progress:
+            task = progress.add_task("Fetching profile...", total=None)
+
+            def callback(message: str, _ratio: float) -> None:
+                progress.update(task, description=message)
+
+            profile = fetch_profile(username, token=token, no_cache=no_cache, progress_callback=callback)
+
+        report = build_report(profile, roast_mode=roast)
+
+        if output_format == "json":
+            rendered = json_output.render(report)
+        elif output_format == "markdown":
+            rendered = markdown_output.render(report)
+        else:
+            rendered = terminal.render(report, no_color=no_color)
+
+        if save_path:
+            with open(save_path, "w", encoding="utf-8") as f:
+                f.write(rendered)
+            console.print(f"Report saved to [bold]{save_path}[/bold]")
+
+        print(rendered, end="")
+
+    except UserNotFoundError:
+        console.print(f"[red]Error:[/red] GitHub user '{username}' not found.")
+        sys.exit(1)
+    except RateLimitError as exc:
+        console.print(f"[red]Rate limit:[/red] {exc.message}")
+        sys.exit(1)
+    except GitHubError as exc:
+        console.print(f"[red]GitHub API error:[/red] {exc.message}")
+        sys.exit(1)
+    except Exception as exc:
+        console.print(f"[red]Unexpected error:[/red] {exc}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

utopia/formatters/__init__.py

@@ -0,0 +1 @@
+"""Output formatters for UTOPIA reports."""

utopia/formatters/json_output.py

@@ -0,0 +1,50 @@
+"""JSON output formatter."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import Any
+
+from utopia.report import Report
+
+
+def render(report: Report) -> str:
+    """Render the report as a structured JSON string."""
+    data: dict[str, Any] = {
+        "username": report.username,
+        "score": {
+            "total": report.score.total,
+            "max": report.score.max_score,
+            "grade": report.score.grade,
+            "breakdown": [
+                {
+                    "category": b.category,
+                    "label": b.label,
+                    "score": b.score,
+                    "max_score": b.max_score,
+                }
+                for b in report.score.breakdown
+            ],
+        },
+        "archetypes": [
+            {"key": a.key, "label": a.label, "percentage": a.percentage}
+            for a in report.archetypes
+        ],
+        "recruiter": {
+            "verdict": report.recruiter.verdict,
+            "reasons": report.recruiter.reasons,
+            "concerns": report.recruiter.concerns,
+        },
+        "strengths": report.strengths,
+        "weaknesses": report.weaknesses,
+        "tech_stack": {
+            "languages": report.profile.total_languages,
+        },
+        "improvement_plan": report.improvement_plan.weeks,
+    }
+
+    if report.roast:
+        data["roast"] = report.roast.lines
+
+    return json.dumps(data, indent=2)

utopia/formatters/markdown_output.py

@@ -0,0 +1,96 @@
+"""Markdown output formatter."""
+
+from __future__ import annotations
+
+from utopia.report import Report
+
+
+def _bar(value: float, width: int = 20) -> str:
+    filled = int(round(max(0.0, min(1.0, value)) * width))
+    return "|" * filled + "-" * (width - filled)
+
+
+def render(report: Report) -> str:
+    """Render the report as a Markdown document."""
+    lines: list[str] = []
+    lines.append(f"# UTOPIA Portfolio Report: {report.username}")
+    lines.append("")
+    lines.append(f"**UTOPIA Score:** {report.score.total:.0f}/{report.score.max_score:.0f}")
+    lines.append(f"**Portfolio Grade:** {report.score.grade}")
+    lines.append("")
+
+    lines.append("## Score Breakdown")
+    lines.append("")
+    lines.append("| Category | Score | Percentage |")
+    lines.append("| --- | --- | --- |")
+    for b in report.score.breakdown:
+        ratio = b.score / b.max_score
+        lines.append(f"| {b.label} | {b.score:.0f}/{b.max_score:.0f} | {_bar(ratio)} {ratio*100:.0f}% |")
+    lines.append("")
+
+    if report.archetypes:
+        lines.append("## Developer Archetype")
+        lines.append("")
+        for arch in report.archetypes:
+            lines.append(f"- **{arch.label}:** {arch.percentage}%")
+        lines.append("")
+
+    lines.append("## Recruiter Verdict")
+    lines.append("")
+    lines.append(f"**Would I hire this developer?** {report.recruiter.verdict}")
+    if report.recruiter.reasons:
+        lines.append("")
+        lines.append("### Reasons")
+        for reason in report.recruiter.reasons:
+            lines.append(f"- {reason}")
+    if report.recruiter.concerns:
+        lines.append("")
+        lines.append("### Concerns")
+        for concern in report.recruiter.concerns:
+            lines.append(f"- {concern}")
+    lines.append("")
+
+    lines.append("## Strengths & Weaknesses")
+    lines.append("")
+    lines.append("### Strengths")
+    for s in report.strengths:
+        lines.append(f"- {s}")
+    lines.append("")
+    lines.append("### Weaknesses")
+    for w in report.weaknesses:
+        lines.append(f"- {w}")
+    lines.append("")
+
+    if report.profile.total_languages:
+        lines.append("## Tech Stack Breakdown")
+        lines.append("")
+        total = sum(report.profile.total_languages.values())
+        sorted_langs = sorted(
+            report.profile.total_languages.items(), key=lambda x: x[1], reverse=True
+        )
+        top = sorted_langs[:4]
+        other = sum(b for _, b in sorted_langs[4:])
+        rows = [(lang, b) for lang, b in top]
+        if other:
+            rows.append(("Other", other))
+        for lang, bytes_count in rows:
+            pct = bytes_count / total if total else 0
+            lines.append(f"- **{lang}:** {_bar(pct)} {pct*100:.1f}%")
+        lines.append("")
+
+    if report.roast:
+        lines.append("## Portfolio Roast")
+        lines.append("")
+        for line in report.roast.lines:
+            lines.append(f"> {line}")
+        lines.append("")
+
+    lines.append("## 30-Day Upgrade Plan")
+    lines.append("")
+    for i, week in enumerate(report.improvement_plan.weeks, start=1):
+        lines.append(f"### Week {i}")
+        for action in week:
+            lines.append(f"- {action}")
+        lines.append("")
+
+    return "\n".join(lines)

utopia/formatters/terminal.py

@@ -0,0 +1,130 @@
+"""Rich-based terminal output formatter."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from utopia.report import Report
+
+
+def _color_for_ratio(ratio: float, no_color: bool) -> str:
+    if no_color:
+        return "white"
+    if ratio >= 0.7:
+        return "green"
+    if ratio >= 0.4:
+        return "yellow"
+    return "red"
+
+
+def _bar(value: float, width: int = 30) -> str:
+    filled = int(round(_clamp(value, 0.0, 1.0) * width))
+    return "█" * filled + "░" * (width - filled)
+
+
+def _clamp(value: float, lower: float, upper: float) -> float:
+    return max(lower, min(upper, value))
+
+
+def render(report: Report, no_color: bool = False) -> str:
+    console = Console(
+        no_color=no_color,
+        force_terminal=True,
+        color_system=None if no_color else "auto",
+        highlight=False,
+    )
+    with console.capture() as capture:
+        console.print()
+
+        # Header panel
+        header_text = Text()
+        header_text.append(f"UTOPIA Portfolio Report: {report.username}\n", style="bold cyan")
+        header_text.append(f"UTOPIA SCORE: {report.score.total:.0f}/{report.score.max_score:.0f}\n", style="bold")
+        header_text.append(f"Portfolio Grade: {report.score.grade}", style="bold")
+        console.print(Panel(header_text, expand=False))
+
+        # Score breakdown
+        table = Table(title="Score Breakdown", show_header=True, header_style="bold magenta")
+        table.add_column("Category", justify="left")
+        table.add_column("Score", justify="right")
+        table.add_column("Bar", justify="left")
+
+        for b in report.score.breakdown:
+            ratio = b.score / b.max_score
+            color = _color_for_ratio(ratio, no_color)
+            table.add_row(
+                b.label,
+                f"{b.score:.0f}/{b.max_score:.0f}",
+                Text(f"{_bar(ratio)} {ratio*100:.0f}%", style=color),
+            )
+        console.print(table)
+
+        # Archetypes
+        if report.archetypes:
+            console.print()
+            console.print("[bold]You are:[/bold]")
+            for arch in report.archetypes:
+                bar = _bar(arch.percentage / 100, width=20)
+                console.print(f"  {arch.label:<22} {bar} {arch.percentage:>5}%")
+
+        # Recruiter verdict
+        console.print()
+        verdict_color = {"YES": "green", "MAYBE": "yellow", "NOT YET": "red"}.get(
+            report.recruiter.verdict, "white"
+        )
+        console.print("[bold]Would I hire this developer?[/bold]")
+        console.print(f"[{verdict_color} bold]{report.recruiter.verdict}[/{verdict_color} bold]")
+        if report.recruiter.reasons:
+            console.print("[bold]Reasons:[/bold]")
+            for reason in report.recruiter.reasons:
+                console.print(f"  ✓ {reason}")
+        if report.recruiter.concerns:
+            console.print("[bold]Concerns:[/bold]")
+            for concern in report.recruiter.concerns:
+                console.print(f"  ✗ {concern}")
+
+        # Strengths / weaknesses
+        console.print()
+        console.print("[bold green]Strengths:[/bold green]")
+        for s in report.strengths:
+            console.print(f"  ✓ {s}")
+        console.print("[bold red]Weaknesses:[/bold red]")
+        for w in report.weaknesses:
+            console.print(f"  ✗ {w}")
+
+        # Tech stack
+        if report.profile.total_languages:
+            console.print()
+            console.print("[bold]Tech Stack Breakdown[/bold]")
+            total = sum(report.profile.total_languages.values())
+            sorted_langs = sorted(
+                report.profile.total_languages.items(), key=lambda x: x[1], reverse=True
+            )
+            top = sorted_langs[:4]
+            other = sum(b for _, b in sorted_langs[4:])
+            rows = [(lang, b) for lang, b in top]
+            if other:
+                rows.append(("Other", other))
+            for lang, bytes_count in rows:
+                pct = bytes_count / total if total else 0
+                bar = _bar(pct, width=20)
+                console.print(f"  {lang:<14} {bar} {pct*100:>5.1f}%")
+
+        # Roast
+        if report.roast:
+            console.print()
+            console.print(Panel("\n".join(report.roast.lines), title="[bold red]Roast Mode[/bold red]", border_style="red"))
+
+        # Improvement plan
+        console.print()
+        console.print("[bold]30-Day Upgrade Plan[/bold]")
+        for i, week in enumerate(report.improvement_plan.weeks, start=1):
+            console.print(f"[bold]Week {i}:[/bold]")
+            for action in week:
+                console.print(f"  • {action}")
+
+        console.print()
+    return capture.get()