visualagents 0.1.0__py3-none-any.whl

visualagents/collector.py

@@ -0,0 +1,146 @@
+"""Collects the source files of a project that are most likely to define agents.
+
+Secrets never leave the machine: env/key files are skipped and anything that looks
+like an API key is redacted before file contents are handed to an LLM.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "venv", "env", ".env", ".tox",
+    ".nox", ".mypy_cache", ".pytest_cache", ".ruff_cache", "dist", "build", "site-packages",
+    ".idea", ".vscode", ".next", ".turbo", "coverage", ".visualagents", ".ipynb_checkpoints",
+    "target", "vendor", ".cache", "htmlcov", "migrations",
+}
+SOURCE_EXTS = {".py", ".ts", ".tsx", ".js", ".mjs", ".cjs", ".jsx", ".yaml", ".yml", ".toml", ".json", ".ipynb", ".md"}
+SECRET_NAMES = re.compile(r"(^\.env)|(\.(pem|key|p12|pfx|crt)$)|(secret|credential|password|token)", re.I)
+MAX_FILE_BYTES = 400_000
+
+AGENT_HINTS = re.compile(
+    r"\b(agent|agents|crew|crewai|autogen|langgraph|langchain|StateGraph|add_node|add_edge|handoff|"
+    r"supervisor|swarm|tool|tools|llm|chat_model|ChatOpenAI|ChatAnthropic|prompt|system_message|"
+    r"instructions|role|backstory|goal|task|workflow|orchestrat\w*|planner|executor|router|"
+    r"GroupChat|AssistantAgent|Runner\.run|create_react_agent|function_call)\b",
+    re.I,
+)
+NAME_HINTS = re.compile(r"(agent|crew|graph|workflow|flow|team|main|app|orchestr|pipeline|node|task|config)", re.I)
+
+SECRET_PATTERNS = [
+    re.compile(r"sk-ant-[A-Za-z0-9_\-]{10,}"),
+    re.compile(r"sk-[A-Za-z0-9_\-]{20,}"),
+    re.compile(r"(?:AKIA|ASIA)[A-Z0-9]{16}"),
+    re.compile(r"gh[pousr]_[A-Za-z0-9]{20,}"),
+    re.compile(r"xox[baprs]-[A-Za-z0-9\-]{10,}"),
+    re.compile(r"AIza[0-9A-Za-z_\-]{30,}"),
+    re.compile(r"""(?i)((?:api[_-]?key|secret|token|password)\s*[:=]\s*["'])([^"']{8,})(["'])"""),
+]
+
+
+@dataclass
+class SourceFile:
+    path: Path
+    rel: str
+    text: str
+    score: float
+
+
+def redact(text: str) -> str:
+    for pat in SECRET_PATTERNS:
+        if pat.groups >= 3:
+            text = pat.sub(lambda m: f"{m.group(1)}<redacted>{m.group(3)}", text)
+        else:
+            text = pat.sub("<redacted>", text)
+    return text
+
+
+def _read(path: Path) -> str | None:
+    try:
+        if path.stat().st_size > MAX_FILE_BYTES:
+            return None
+        raw = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    if path.suffix == ".ipynb":
+        try:
+            nb = json.loads(raw)
+            cells = [
+                "".join(c.get("source", [])) for c in nb.get("cells", []) if c.get("cell_type") == "code"
+            ]
+            raw = "\n\n# %% cell\n".join(cells)
+        except (ValueError, AttributeError):
+            return None
+    return raw
+
+
+def iter_files(root: Path):
+    root = Path(root)
+    if root.is_file():
+        yield root
+        return
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(
+            d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".") and not d.endswith(".egg-info")
+        )
+        for name in sorted(filenames):
+            p = Path(dirpath) / name
+            if p.suffix.lower() not in SOURCE_EXTS or SECRET_NAMES.search(name):
+                continue
+            if name in {"package-lock.json", "poetry.lock", "uv.lock", "yarn.lock", "pnpm-lock.yaml"}:
+                continue
+            yield p
+
+
+def collect(root: Path, max_files: int = 400) -> list[SourceFile]:
+    """All candidate files, ranked by how agent-related they look (highest first)."""
+    root = Path(root).resolve()
+    base = root if root.is_dir() else root.parent
+    out: list[SourceFile] = []
+    for p in iter_files(root):
+        text = _read(p)
+        if not text or not text.strip():
+            continue
+        rel = str(p.relative_to(base))
+        hits = len(AGENT_HINTS.findall(text))
+        score = hits / (1 + len(text) / 4000) + hits * 0.05
+        if NAME_HINTS.search(p.stem):
+            score += 3
+        if p.suffix == ".md":
+            score = 5 if p.stem.lower() == "readme" and rel.count(os.sep) == 0 else score * 0.2
+        if p.suffix in {".json", ".toml"}:
+            score *= 0.3
+        if "test" in rel.lower():
+            score *= 0.3
+        out.append(SourceFile(p, rel, text, score))
+        if len(out) >= max_files * 4:
+            break
+    out.sort(key=lambda f: (-f.score, f.rel))
+    return out[:max_files]
+
+
+def pack(files: list[SourceFile], budget_chars: int = 180_000) -> tuple[str, list[str]]:
+    """Concatenate the best files into one prompt-sized block. Returns (text, included rel paths)."""
+    parts: list[str] = []
+    included: list[str] = []
+    used = 0
+    for f in files:
+        if f.score <= 0 and included:
+            continue
+        body = redact(f.text)
+        numbered = "\n".join(f"{i:>4}| {line}" for i, line in enumerate(body.splitlines(), 1))
+        chunk = f'<file path="{f.rel}">\n{numbered}\n</file>\n'
+        if used + len(chunk) > budget_chars:
+            remaining = budget_chars - used
+            if remaining > 2000:
+                parts.append(chunk[: remaining - 40] + "\n... (truncated)\n</file>\n")
+                included.append(f.rel + " (truncated)")
+            break
+        parts.append(chunk)
+        included.append(f.rel)
+        used += len(chunk)
+    return "".join(parts), included

visualagents/demo/blueprint.json

@@ -0,0 +1,68 @@
+{
+  "version": 1,
+  "project": "research_crew (demo)",
+  "framework": "crewai-style",
+  "summary": "A four-agent research crew. The Planner splits the user's question into sub-questions, the Researcher gathers and verifies sources with web search and paper reading, the Writer drafts a cited report, and the Critic fact-checks it - sending it back to the Writer until it passes review.",
+  "generated_by": "the bundled demo blueprint",
+  "generated_at": "",
+  "agents": [
+    {
+      "id": "planner",
+      "name": "Planner",
+      "role": "Research strategist",
+      "description": "Breaks the user's question into independent sub-questions and a research plan.",
+      "tools": ["outline_builder"],
+      "file": "research_crew.py",
+      "line": 37,
+      "aliases": ["planner", "Research strategist"],
+      "keywords": ["plan", "sub-questions", "outline"]
+    },
+    {
+      "id": "researcher",
+      "name": "Researcher",
+      "role": "Senior research analyst",
+      "description": "Searches the web and reads papers to find and verify evidence for each sub-question.",
+      "tools": ["web_search", "read_paper"],
+      "file": "research_crew.py",
+      "line": 39,
+      "aliases": ["researcher", "Senior research analyst"],
+      "keywords": ["sources", "search", "results", "paper"]
+    },
+    {
+      "id": "writer",
+      "name": "Writer",
+      "role": "Technical writer",
+      "description": "Turns the findings into a clear, structured report with citations; revises after review.",
+      "tools": [],
+      "file": "research_crew.py",
+      "line": 41,
+      "aliases": ["writer", "Technical writer"],
+      "keywords": ["draft", "section", "revising"]
+    },
+    {
+      "id": "critic",
+      "name": "Critic",
+      "role": "Reviewer",
+      "description": "Fact-checks every claim in the draft and either approves it or sends it back with fixes.",
+      "tools": ["fact_check"],
+      "file": "research_crew.py",
+      "line": 42,
+      "aliases": ["critic", "Reviewer"],
+      "keywords": ["claim", "unsupported", "approved", "revise"]
+    }
+  ],
+  "edges": [
+    {"from": "planner", "to": "researcher", "label": "research plan", "conditional": false},
+    {"from": "researcher", "to": "writer", "label": "findings + sources", "conditional": false},
+    {"from": "writer", "to": "critic", "label": "draft", "conditional": false},
+    {"from": "critic", "to": "writer", "label": "revise", "conditional": true}
+  ],
+  "entry": ["planner"],
+  "exits": ["critic"],
+  "steps": [
+    {"order": 1, "title": "Plan", "agents": ["planner"], "description": "Split the question into sub-questions."},
+    {"order": 2, "title": "Research", "agents": ["researcher"], "description": "Gather and verify sources for each sub-question."},
+    {"order": 3, "title": "Draft", "agents": ["writer"], "description": "Write a cited report from the findings."},
+    {"order": 4, "title": "Review", "agents": ["critic"], "description": "Fact-check; loop back to the Writer until approved."}
+  ]
+}

visualagents/demo/research_crew.py

@@ -0,0 +1,146 @@
+"""A simulated multi-agent research crew for `visualagents demo`.
+
+It needs no API key: the agents "think" from a script and print CrewAI-style chain-of-thought,
+exactly the kind of console output VisualAgents maps onto the blueprint. The tiny framework
+below is real enough that `visualagents scan` finds the same four agents statically.
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+import time
+
+SPEED = 1.0
+
+
+class Agent:
+    def __init__(self, name: str, role: str, goal: str, tools: list | None = None):
+        self.name, self.role, self.goal, self.tools = name, role, goal, tools or []
+
+
+class Workflow:
+    def __init__(self):
+        self.edges: list[tuple[str, str]] = []
+
+    def add_edge(self, src: str, dst: str) -> None:
+        self.edges.append((src, dst))
+
+
+def web_search(query: str) -> str: ...
+def read_paper(url: str) -> str: ...
+def outline_builder(question: str) -> str: ...
+def fact_check(claim: str) -> str: ...
+
+
+planner = Agent(name="Planner", role="Research strategist", goal="Break the question into a research plan",
+                tools=[outline_builder])
+researcher = Agent(name="Researcher", role="Senior research analyst", goal="Find and verify sources for each sub-question",
+                   tools=[web_search, read_paper])
+writer = Agent(name="Writer", role="Technical writer", goal="Turn the findings into a clear, cited report")
+critic = Agent(name="Critic", role="Reviewer", goal="Check the draft for unsupported claims and gaps",
+               tools=[fact_check])
+
+flow = Workflow()
+flow.add_edge("planner", "researcher")
+flow.add_edge("researcher", "writer")
+flow.add_edge("writer", "critic")
+flow.add_edge("critic", "writer")
+
+
+def say(text: str = "", pause: float = 0.35) -> None:
+    print(text, flush=True)
+    time.sleep(pause / SPEED * random.uniform(0.7, 1.3))
+
+
+def stream(prefix: str, text: str, pause: float = 0.9) -> None:
+    """Print a thought word-by-word-ish, the way a streaming LLM would."""
+    sys.stdout.write(prefix)
+    for word in text.split(" "):
+        sys.stdout.write(word + " ")
+        sys.stdout.flush()
+        time.sleep(0.035 / SPEED)
+    sys.stdout.write("\n")
+    sys.stdout.flush()
+    time.sleep(pause / SPEED)
+
+
+def agent_header(agent: Agent) -> None:
+    say("")
+    say(f"# Agent: {agent.name}", 0.6)
+
+
+def main() -> None:
+    global SPEED
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--speed", type=float, default=1.0)
+    ap.add_argument("question", nargs="?", default="How are solid-state batteries changing electric vehicles?")
+    args = ap.parse_args()
+    SPEED = max(0.1, args.speed)
+
+    say(f"🚀 Crew: research_crew · question: {args.question!r}", 1.0)
+
+    agent_header(planner)
+    say("## Task: Break the question into a research plan", 0.5)
+    stream("## Thought: ", "The question spans chemistry, manufacturing and market adoption. I should split it so each part can be researched independently.")
+    say("## Using tool: outline_builder")
+    say('## Tool Input: {"question": "solid-state batteries in EVs"}', 0.8)
+    say("## Tool Output: 3 sub-questions: energy density vs Li-ion, manufacturing hurdles, which automakers ship first", 0.8)
+    stream("## Final Answer: ", "Plan → (1) energy density and charging, (2) manufacturing & cost, (3) adoption timeline by automaker.")
+    say("Handing off to Researcher", 0.8)
+
+    agent_header(researcher)
+    say("## Task: Find and verify sources for each sub-question", 0.5)
+    stream("## Thought: ", "Start with sub-question 1. I need recent, quantitative numbers on energy density, ideally from peer-reviewed work or manufacturer data sheets.")
+    say("## Using tool: web_search")
+    say('## Tool Input: {"query": "solid-state battery energy density Wh/kg 2025 prototype"}', 1.0)
+    say("## Tool Output: 8 results — QuantumScape QSE-5 (~844 Wh/L), Toyota sulfide roadmap, Nature Energy review…", 0.9)
+    stream("## Thought: ", "The Nature Energy review summarises lab vs pilot-line numbers. Reading it gives me a credible baseline.")
+    say("## Using tool: read_paper")
+    say('## Tool Input: {"url": "https://doi.org/10.1038/s41560-0xx"}', 1.2)
+    say("## Tool Output: pilot cells reach 350–400 Wh/kg; 10–80% charge in ~15 min; dendrite suppression still limits cycle life", 0.9)
+    stream("## Thought: ", "Sub-question 1 covered. Now manufacturing and cost — dry-room processing and solid electrolyte yield are the usual bottlenecks.")
+    say("## Using tool: web_search")
+    say('## Tool Input: {"query": "solid-state battery manufacturing cost per kWh yield 2025"}', 1.0)
+    say("## Tool Output: analysts estimate 2–3× Li-ion cost today; sulfide electrolytes need moisture-free lines", 0.9)
+    say("## Using tool: web_search")
+    say('## Tool Input: {"query": "automaker solid-state battery production timeline"}', 1.0)
+    say("## Tool Output: Toyota targets 2027–28; Nissan pilot line 2028; Mercedes & Factorial road tests underway", 0.9)
+    stream("## Final Answer: ", "Findings: 350–400 Wh/kg in pilot cells, ~15 min fast-charge, 2–3× cost today, first production cars 2027–28. 6 sources.")
+    say("Passing results to Writer", 0.8)
+
+    agent_header(writer)
+    say("## Task: Turn the findings into a clear, cited report", 0.5)
+    stream("## Thought: ", "Readers care about range, charging time and when they can buy one. I'll lead with those and keep chemistry details brief.")
+    stream("## Thought: ", "Structure: summary, three sections matching the plan, and a short outlook.", 0.6)
+    say("Drafting section 1/3: energy density & charging…", 1.2)
+    say("Drafting section 2/3: manufacturing & cost…", 1.2)
+    say("Drafting section 3/3: who ships first…", 1.2)
+    stream("## Final Answer: ", "Draft v1 ready — 640 words, 6 citations.")
+    say("Handing off to Critic", 0.8)
+
+    agent_header(critic)
+    say("## Task: Check the draft for unsupported claims and gaps", 0.5)
+    stream("## Thought: ", "Check every number against a source. The '50% more range' line in the summary has no citation.")
+    say("## Using tool: fact_check")
+    say('## Tool Input: {"claim": "solid-state packs give 50% more range"}', 1.0)
+    say("## Tool Output: unsupported — sources show +20–40% depending on pack design", 0.9)
+    stream("## Final Answer: ", "REVISE: correct the range claim to 20–40% and cite it; add one sentence on cycle-life risk.")
+    say("Sending the draft back to Writer", 0.8)
+
+    agent_header(writer)
+    stream("## Thought: ", "Fix the range figure, add the citation, and mention dendrite-related cycle-life limits in section 1.")
+    say("Revising summary and section 1…", 1.4)
+    stream("## Final Answer: ", "Draft v2 ready — range claim corrected (20–40%), cycle-life caveat added.")
+    say("Handing off to Critic", 0.8)
+
+    agent_header(critic)
+    stream("## Thought: ", "All quantitative claims now trace to a source and the risks are stated. Good to ship.")
+    stream("## Final Answer: ", "APPROVED ✅")
+    say("")
+    say("✅ Crew finished: report delivered (640 words, 7 citations)", 0.2)
+
+
+if __name__ == "__main__":
+    main()