archo 0.1.0__tar.gz

archo-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: archo
+Version: 0.1.0
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.24.0
+Requires-Dist: platformdirs>=4.9.4
+Requires-Dist: tomli_w>=1.2.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"

archo-0.1.0/README.md

@@ -0,0 +1,88 @@
+# archo
+
+Auto-generate architecture docs from your codebase. Always in sync.
+
+`archo` scans your project, sends the source files to an LLM, and generates an `ARCHO.md` file with a Mermaid architecture diagram and a structured breakdown of routes, dependencies, databases, and pub/sub topics.
+
+```
+$ archo
+Scanning repo: .
+
+Collected (12 files):
+  + src/app.py
+  + src/routes/users.py
+  + src/services/notification.py
+  ...
+
+The following files will be sent to anthropic: [...]
+Would you like to continue? [y/n]: y
+
+Generating ARCHO.md...
+Done — ARCHO.md written.
+```
+
+## Install
+
+```bash
+pip install archo
+```
+
+For OpenAI support:
+
+```bash
+pip install archo[openai]
+```
+
+## Quick start
+
+Run `archo` in any project directory:
+
+```bash
+cd your-project
+archo
+```
+
+On first run, you'll be prompted to configure your LLM provider, model, and API key. Config is stored in your system config directory (e.g. `~/.config/archo/config.toml`).
+
+## Supported providers
+
+| Provider | Models                  | Notes |
+|----------|-------------------------|-------|
+| Anthropic | claude-sonnet-4-6, etc. | Default provider |
+| OpenAI | gpt-5.4, etc.           | Requires `pip install archo[openai]` |
+| Ollama | Any local model         | Requires a running Ollama instance |
+
+## Commands
+
+```bash
+archo              # Generate architecture docs for current directory
+archo init         # First-time setup (provider, model, API key)
+archo provider     # View or change LLM provider
+archo model        # View or change model
+archo api-key      # View or change API key
+archo llm-host     # View or change Ollama host URL
+```
+
+## What it generates
+
+`archo` creates an `ARCHO.md` file containing:
+
+- **Mermaid diagram** — visual map of your service, its routes, outbound calls, databases, and pub/sub topics
+- **Routes** — all HTTP endpoints with methods and paths
+- **Outbound calls** — services your code talks to and how (REST, gRPC, SDK, etc.)
+- **Pub/Sub** — topics your service publishes to and subscribes from
+- **Databases** — database types and their collections/tables
+
+## Security
+
+`archo` never sends sensitive files to any LLM provider. The following are always excluded:
+
+- `.env`, `.env.production`, `.env.prod`
+- `*.pem`, `*.key`, `*.p12`
+- `secrets.yaml`, `credentials.json`
+
+Large files (>50KB), lock files, logs, and common non-source directories (`node_modules`, `.venv`, `__pycache__`, etc.) are also skipped.
+
+## License
+
+MIT

archo-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "archo"
+version = "0.1.0"
+dependencies = [
+    "anthropic>=0.84.0",
+    "python-dotenv>=1.2.2",
+    "pydantic>=2.0",
+    "typer>=0.24.0",
+    "platformdirs>=4.9.4",
+    "tomli_w>=1.2.0"
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+archo = "archo.main:app"

archo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

archo-0.1.0/src/archo/collector/file_collector.py

@@ -0,0 +1,91 @@
+import os
+
+BLOCKED_FILES = {
+    ".env",
+    ".env.production",
+    ".env.prod",
+    "secrets.yaml",
+    "credentials.json",
+    ".gitignore",
+}
+
+BLOCKED_EXTENSIONS = {".pem", ".key", ".p12"}
+
+SKIP_DIRS = {
+    "tests", "test", "__pycache__", "node_modules",
+    "dist", "build", ".venv", "venv", "migrations", ".git",
+}
+
+SKIP_EXTENSIONS = {".lock", ".log", ".md", ".txt", ".d.ts"}
+
+MAX_FILE_SIZE = 50 * 1024  # 50kb
+
+
+def is_blocked(file_path: str) -> bool:
+    """Return True if this file must never be sent."""
+    name = os.path.basename(file_path)
+    _, ext = os.path.splitext(name)
+    return name in BLOCKED_FILES or ext in BLOCKED_EXTENSIONS
+
+
+def collect_files(repo_path: str = ".") -> tuple[str, list[str]]:
+    """Walk repo_path, collect relevant files, and return a single bundled string."""
+    print(f"Scanning repo: {repo_path}\n")
+    bundle = []
+    collected_paths = []
+    skipped = []
+
+    for root, dirs, files in os.walk(repo_path):
+        dirs[:] = [
+            d for d in dirs
+            if d not in SKIP_DIRS and not d.startswith(".")
+        ]
+
+        for filename in sorted(files):
+            full_path = os.path.join(root, filename)
+            rel_path = os.path.relpath(full_path, repo_path)
+            _, ext = os.path.splitext(filename)
+
+            if is_blocked(full_path):
+                skipped.append((rel_path, "blocked"))
+                continue
+
+            if ext in SKIP_EXTENSIONS:
+                skipped.append((rel_path, "skipped extension"))
+                continue
+
+            try:
+                size = os.path.getsize(full_path)
+            except Exception as e:
+                print(f"  Error checking size of {rel_path}: {e}")
+                continue
+
+            if size > MAX_FILE_SIZE:
+                skipped.append((rel_path, f"too large ({size // 1024}kb)"))
+                continue
+
+            try:
+                with open(full_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+            except Exception as e:
+                print(f"  Error reading {rel_path}: {e}")
+                continue
+
+            bundle.append(f"### {rel_path}\n{content}")
+            collected_paths.append(rel_path)
+
+    # Summary
+    print(f"Collected ({len(bundle)} files):")
+    for path in collected_paths:
+        print(f"  + {path}")
+
+    print(f"\nSkipped ({len(skipped)} files):")
+    for path, reason in skipped:
+        print(f"  - {path}  [{reason}]")
+
+    if not bundle:
+        print("\nNo files collected.")
+        return "", []
+
+    print(f"\nDone.")
+    return "\n\n".join(bundle), collected_paths

archo-0.1.0/src/archo/config.py

@@ -0,0 +1,88 @@
+import os
+import tomllib
+import tomli_w
+from platformdirs import user_config_dir
+
+CONFIG_DIR = user_config_dir("archo")
+CONFIG_PATH = os.path.join(CONFIG_DIR, "config.toml")
+
+def config_exists() -> bool:
+    """Check if config file exists."""
+    return os.path.exists(CONFIG_PATH)
+
+def setup_config(provider: str, model: str, api_key: str, host_url: str = None) -> None:
+    """Setup .archo/config file"""
+    if not config_exists():
+
+        os.makedirs(CONFIG_DIR, exist_ok=True)
+
+        with open(CONFIG_PATH, "x") as f:
+            f.write("[llm-setup]\n")
+            f.write(f'LLM_PROVIDER = "{provider}"\n')
+            f.write(f'LLM_MODEL = "{model}"\n')
+            f.write(f'LLM_API_KEY= "{api_key}"\n')
+            if host_url:
+                f.write(f'OLLAMA_HOST= "{host_url}"\n')
+
+def get_config() -> dict:
+    """Get .archo/config file"""
+    if config_exists():
+        with open(CONFIG_PATH, "rb") as config_file:
+            try:
+                config_dict = tomllib.load(config_file)
+            except tomllib.TOMLDecodeError:
+                raise ValueError("Config file is corrupted")
+
+        return config_dict
+    raise FileNotFoundError("Config file not found")
+
+def update_config(config: dict) -> None:
+    """Update .archo/config file"""
+    with open(CONFIG_PATH, "wb") as config_file:
+        tomli_w.dump(config, config_file)
+
+def get_model() -> str:
+    """Get current model from config file"""
+    config = get_config()
+    return config.get("llm-setup", {}).get("LLM_MODEL", "No model set")
+
+def get_provider() -> str:
+    """Get current provider from config file"""
+    config = get_config()
+    return config.get("llm-setup", {}).get("LLM_PROVIDER", "No provider set")
+
+def update_model(model: str) -> None:
+    """Update current model from config file"""
+    config = get_config()
+    config["llm-setup"]["LLM_MODEL"] = model
+    update_config(config)
+
+def update_provider(provider: str) -> None:
+    """Update current provider from config file"""
+    config = get_config()
+    config["llm-setup"]["LLM_PROVIDER"] = provider
+    update_config(config)
+
+def get_api_key() -> str:
+    """Get current API key from config file"""
+    config = get_config()
+    return config.get("llm-setup", {}).get("LLM_API_KEY", "No API key set")
+
+def update_api_key(api_key: str) -> None:
+    """Update current API key in config file"""
+    config = get_config()
+    config["llm-setup"]["LLM_API_KEY"] = api_key
+    update_config(config)
+
+def get_llm_host() -> str | None:
+    """Get current Ollama host URL from config file, or None if not set"""
+    config = get_config()
+    return config.get("llm-setup", {}).get("OLLAMA_HOST", None)
+
+def update_llm_host(host_url: str) -> None:
+    """Update current Ollama host URL in config file"""
+    config = get_config()
+    config["llm-setup"]["OLLAMA_HOST"] = host_url
+    update_config(config)
+
+

archo-0.1.0/src/archo/llm/__init__.py

@@ -0,0 +1 @@
+

archo-0.1.0/src/archo/llm/llm_client.py

@@ -0,0 +1,33 @@
+import os
+
+from archo.llm.providers.llm_base import LLMProvider
+from archo.schemas.architecture import ArchitectureResponse
+
+
+def build_prompt(file_bundle: str) -> str:
+    """Build the user prompt wrapping the collected file bundle."""
+    return f"Analyze these service files and return the architecture JSON:\n\n{file_bundle}"
+
+def get_provider(provider: str, model, api_key_value: str = None, llm_host: str = None) -> LLMProvider:
+    """Return an instance of the configured provider."""
+    if provider == "anthropic":
+        from archo.llm.providers.anthropic import AnthropicProvider
+        return AnthropicProvider(api_key_value, model)
+    elif provider == "openai":
+        from archo.llm.providers.openai import OpenAIProvider
+        return OpenAIProvider(api_key_value, model)
+    elif provider == "ollama":
+        from archo.llm.providers.ollama import OllamaProvider
+        return OllamaProvider(model, llm_host)
+    else:
+        raise ValueError(f"Unknown LLM_PROVIDER '{provider}'. Supported: anthropic, openai, ollama")
+
+
+def call_llm(file_bundle: str, provider: str, model: str, api_key_value: str = None, llm_host: str = None) -> ArchitectureResponse:
+    """Send the file bundle to the configured LLM provider and return parsed architecture JSON."""
+    provider = get_provider(provider, model, api_key_value, llm_host)
+    prompt = build_prompt(file_bundle)
+
+    architecture_response = provider.call(prompt)
+
+    return architecture_response

archo-0.1.0/src/archo/llm/prompt.py

@@ -0,0 +1,21 @@
+SYSTEM_PROMPT = """You are a code analysis assistant. Analyze the provided service files and extract architecture information.
+
+Return ONLY valid JSON matching this exact schema — no markdown, no explanation, just JSON:
+
+{
+  "service_name": string,
+  "language": string,
+  "framework": string,
+  "routes": [{ "method": string, "path": string }],
+  "outbound_calls": [{ "target_service": string, "via": string }],
+  "pubsub": { "subscribes": [string], "publishes": [string] },
+  "databases": [{ "type": string, "collections_or_tables": [string] }]
+}
+
+Rules for classification:
+- "framework" refers to the primary web or application framework (e.g. Flask, FastAPI, Express, Spring). CLI libraries (e.g. Typer, Click, argparse), build tools, and utility packages are not frameworks — use "none" if no application framework is detected.
+- "outbound_calls" includes ALL calls to services or APIs outside this codebase — internal services (e.g. orders-service), third-party APIs (e.g. Stripe, Twilio), and SDK-based integrations (e.g. boto3 for S3). Use "via" to describe how the call is made (HTTP, SDK, gRPC, etc.).
+- "databases" refers only to actual database systems (e.g. PostgreSQL, MongoDB, Redis, DynamoDB). File system reads/writes and local config files are not databases — use an empty array if none are present.
+- "pubsub" refers strictly to message broker patterns (e.g. Redis Pub/Sub channels, Kafka topics, RabbitMQ exchanges).
+  Do NOT classify Redis job queues (e.g. enqueue_job, arq, rq, celery) as pubsub — those belong in "databases" with type "redis".
+"""

archo-0.1.0/src/archo/llm/providers/anthropic.py

@@ -0,0 +1,41 @@
+import anthropic as anthropic_sdk
+from archo.llm.prompt import SYSTEM_PROMPT
+from archo.llm.providers.llm_base import LLMProvider
+from archo.schemas.architecture import ArchitectureResponse
+
+
+class AnthropicProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str):
+        self.api_key = api_key
+        self.client = anthropic_sdk.Anthropic(api_key=self.api_key)
+        self.model = model
+
+    def call(self, file_bundle: str) -> ArchitectureResponse:
+        """Send file bundle to Anthropic and return response text."""
+        print(f"Sending to Anthropic ({self.model})...")
+
+        try:
+            with self.client.messages.stream(
+                model=self.model,
+                max_tokens=4096,
+                system=SYSTEM_PROMPT,
+                messages=[{"role": "user", "content": file_bundle}],
+                output_format=ArchitectureResponse,
+            ) as stream:
+                response = stream.get_final_message()
+        except anthropic_sdk.AuthenticationError:
+            raise RuntimeError("Invalid API key — check LLM_API_KEY.")
+        except anthropic_sdk.APIConnectionError:
+            raise RuntimeError("Could not connect to Anthropic API — check your network.")
+        except anthropic_sdk.APIStatusError as e:
+            raise RuntimeError(f"Anthropic API error ({e.status_code}): {e.message}")
+
+        for block in response.content:
+            if block.type == "text":
+                try:
+                    architecture_response = ArchitectureResponse.model_validate_json(block.text)
+                    return architecture_response
+                except Exception as e:
+                    raise RuntimeError(f"Failed to parse Anthropic response: {e}")
+
+        raise RuntimeError("Anthropic returned an empty response.")

archo-0.1.0/src/archo/llm/providers/llm_base.py

@@ -0,0 +1,5 @@
+from archo.schemas.architecture import ArchitectureResponse
+
+class LLMProvider:
+    def call(self, file_bundle: str) -> ArchitectureResponse:
+        raise NotImplementedError

archo-0.1.0/src/archo/llm/providers/ollama.py

@@ -0,0 +1,48 @@
+import json
+import urllib.request
+import urllib.error
+from archo.llm.prompt import SYSTEM_PROMPT
+from archo.llm.providers.llm_base import LLMProvider
+from archo.schemas.architecture import ArchitectureResponse
+
+
+class OllamaProvider(LLMProvider):
+    def __init__(self, model: str, ollama_host: str):
+        self.host = ollama_host
+        self.model = model
+
+    def call(self, file_bundle: str) -> ArchitectureResponse:
+        """Send file bundle to Ollama and return response text."""
+        url = f"{self.host}/api/chat"
+
+        payload = json.dumps({
+            "model": self.model,
+            "stream": False,
+            "format": "json",
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": file_bundle},
+            ],
+        }).encode("utf-8")
+
+        print(f"Sending to Ollama ({self.model} @ {self.host})...")
+
+        req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
+
+        try:
+            with urllib.request.urlopen(req) as resp:
+                body = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"Could not connect to Ollama at {self.host} — is it running? ({e.reason})")
+        except json.JSONDecodeError:
+            raise RuntimeError("Ollama returned an invalid response.")
+
+        text = body.get("message", {}).get("content", "")
+        if not text:
+            raise RuntimeError("Ollama returned an empty response.")
+
+        try:
+            architecture_response = ArchitectureResponse.model_validate_json(text)
+            return architecture_response
+        except Exception as e:
+            raise RuntimeError(f"Failed to parse Ollama response: {e}")

archo-0.1.0/src/archo/llm/providers/openai.py

@@ -0,0 +1,42 @@
+from archo.llm.prompt import SYSTEM_PROMPT
+from archo.llm.providers.llm_base import LLMProvider
+from archo.schemas.architecture import ArchitectureResponse
+
+
+class OpenAIProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str):
+        try:
+            import openai
+        except ImportError:
+            raise ImportError("OpenAI provider requires the openai package. Install with: pip install archo[openai]")
+
+        self.api_key = api_key
+        self._openai_sdk = openai
+        self.client = openai.OpenAI(api_key=self.api_key)
+        self.model = model
+
+    def call(self, file_bundle: str) -> ArchitectureResponse:
+        """Send file bundle to OpenAI and return response text."""
+        print(f"Sending to OpenAI ({self.model})...")
+
+        try:
+            response = self.client.chat.completions.parse(
+                model=self.model,
+                max_completion_tokens=4096,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": file_bundle},
+                ],
+                response_format=ArchitectureResponse,
+            )
+        except self._openai_sdk.AuthenticationError:
+            raise RuntimeError("Invalid API key — check LLM_API_KEY.")
+        except self._openai_sdk.APIConnectionError:
+            raise RuntimeError("Could not connect to OpenAI API — check your network.")
+        except self._openai_sdk.APIStatusError as e:
+            raise RuntimeError(f"OpenAI API error ({e.status_code}): {str(e)}")
+
+        if not response.choices:
+            raise RuntimeError("OpenAI returned an empty response.")
+
+        return response.choices[0].message.parsed

archo-0.1.0/src/archo/main.py

@@ -0,0 +1,152 @@
+import typer
+from importlib.metadata import version
+
+from archo.config import (
+    config_exists, setup_config, get_config,
+    get_provider, update_provider,
+    get_model, update_model,
+    get_api_key, update_api_key,
+    get_llm_host, update_llm_host,
+)
+from archo.llm.llm_client import call_llm
+from archo.collector.file_collector import collect_files
+from archo.output.output_generator import write_output
+
+app = typer.Typer()
+
+def version_callback(value: bool):
+    if value:
+        typer.echo(f"archo {version('archo')}")
+        raise typer.Exit()
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(None, "--version", "-v", callback=version_callback, is_eager=True, help="Show version and exit."),
+):
+    """
+    Sets up archo for the first time if .archo/config doesn't exist
+    Reads in all the files in the current working directory ignoring sensitive files
+    Sends those files to be interpreted by the LLM of your choice and return a structured response
+    An ARCHO.md file is created with a high level overview of the application's architecture
+    """
+    if ctx.invoked_subcommand or version:
+        return
+
+    if not config_exists():
+        init()
+
+    file_string, file_list = collect_files()
+
+    if file_string:
+        provider_name = get_provider()
+
+        user_response = typer.prompt(f"The following files will be sent to {provider_name}: {file_list}\nWould you like to continue? [y/n]")
+
+        if user_response.lower() == "n" or user_response.lower() == "no":
+            typer.echo("Aborting.")
+            raise typer.Exit()
+
+        model_name = get_model()
+        llm_host_value = get_llm_host()
+        api_key_value = get_api_key()
+        result = call_llm(file_string, provider_name, model_name, api_key_value, llm_host_value)
+        write_output(result)
+
+@app.command()
+def init():
+    """
+    Sets up .archo/config for the first time.
+    Prompts user for provider, model and API Key
+    Prompts user OLLAMA_HOST if provider is ollama
+    Adds ./archo to .gitignore if it's not already there
+    """
+
+    if config_exists():
+        typer.echo("Config file already exists. Run archo --help for available commands.")
+        raise typer.Exit(1)
+
+    typer.echo("Welcome to Archo! Let's get you set up.")
+
+    llm_api_key = None
+    llm_host_url = None
+
+    llm_provider = typer.prompt("What LLM provider would you like to use? (anthropic, openai, ollama)", default="anthropic", show_default=True)
+    llm_model = typer.prompt("What model would you like to use? e.g. claude-sonnet-4-6, gpt-5.3-instant, or your own for ollama")
+
+    if llm_provider == "ollama":
+        llm_host_url = typer.prompt("Enter your LLM host URL")
+    else:
+        llm_api_key = typer.prompt("Enter your API Key.  It must correspond to the provider you selected.", hide_input=True)
+
+    setup_config(llm_provider, llm_model, llm_api_key, llm_host_url)
+
+@app.command()
+def model():
+    """
+    Displays current model being used
+    Allows user to change their model
+    """
+    typer.echo(f"Current model: {get_model()}")
+    model_response =  typer.prompt("Enter new model to switch or press enter to keep current", default="", show_default=False)
+    if model_response:
+        update_model(model_response)
+        typer.echo(f"Model updated to {model_response}")
+    else:
+        typer.echo("Model unchanged")
+
+@app.command()
+def provider():
+    """
+    Displays current provider being used
+    Allows user to change their provider
+    Allows user to change their model
+    """
+    typer.echo(f"Current provider: {get_provider()}")
+    provider_response =  typer.prompt("Enter new provider to switch or press enter to keep current", default="", show_default=False)
+    if provider_response:
+        update_provider(provider_response)
+        typer.echo(f"Provider updated to {provider_response}")
+
+        if provider_response.lower() == "ollama":
+            typer.echo("Since you switched to Ollama, you'll need to set your LLM host URL.")
+            llm_host()
+
+        model_response = typer.prompt("Would you like to update your model as well? (y/n)", default="y",
+                                      show_default=True)
+        if model_response.lower() == "y" or model_response.lower() == "yes":
+            model()
+    else:
+        typer.echo("Provider unchanged")
+
+@app.command()
+def api_key():
+    """
+    Displays current API key being used
+    Allows user to change their API key
+    """
+    typer.echo(f"Current API key: {get_api_key()}")
+    key_response = typer.prompt("Enter new API key to switch or press enter to keep current", default="", show_default=False, hide_input=True)
+    if key_response:
+        update_api_key(key_response)
+        typer.echo("API key updated")
+    else:
+        typer.echo("API key unchanged")
+
+@app.command()
+def llm_host():
+    """
+    Displays current Ollama host URL
+    Allows user to change their Ollama host URL
+    """
+    current = get_llm_host()
+    if current is None:
+        typer.echo("No Ollama host set")
+    else:
+        typer.echo(f"Current Ollama host: {current}")
+    host_response = typer.prompt("Enter new Ollama host URL or press enter to keep current", default="", show_default=False)
+    if host_response:
+        update_llm_host(host_response)
+        typer.echo(f"Ollama host updated to {host_response}")
+    else:
+        typer.echo("Ollama host unchanged")

archo-0.1.0/src/archo/output/markdown_generator.py

@@ -0,0 +1,57 @@
+from archo.schemas.architecture import ArchitectureResponse
+
+
+def generate_markdown(data: ArchitectureResponse) -> str:
+    """Convert architecture JSON into a readable ARCHO.md string."""
+    lines = []
+
+    lines.append(f"# {data.service_name}")
+    lines.append("")
+    lines.append(f"**Language:** {data.language}  ")
+    if data.framework != "none":
+        lines.append(f"**Framework:** {data.framework}  ")
+    lines.append("")
+
+    if data.routes:
+        lines.append("## Routes")
+        lines.append("")
+        for r in data.routes:
+            lines.append(f"- `{r.method}` {r.path}")
+        lines.append("")
+
+    outbound = data.outbound_calls or []
+    if outbound:
+        lines.append("## Outbound Calls")
+        lines.append("")
+        for call in outbound:
+            lines.append(f"- **{call.target_service}** via {call.via}")
+        lines.append("")
+
+    if data.pubsub:
+        subscribes = data.pubsub.subscribes
+        publishes = data.pubsub.publishes
+        if subscribes or publishes:
+            lines.append("## Pub/Sub")
+            lines.append("")
+            if subscribes:
+                lines.append("**Subscribes:**")
+                for topic in subscribes:
+                    lines.append(f"- {topic}")
+            if publishes:
+                lines.append("**Publishes:**")
+                for topic in publishes:
+                    lines.append(f"- {topic}")
+            lines.append("")
+
+    databases = data.databases or []
+    if databases:
+        lines.append("## Databases")
+        lines.append("")
+        for db in databases:
+            if db.collections_or_tables:
+                lines.append(f"**{db.type}:** {', '.join(db.collections_or_tables)}")
+            else:
+                lines.append(f"**{db.type}**")
+        lines.append("")
+
+    return "\n".join(lines)

archo-0.1.0/src/archo/output/mermaid_generator.py

@@ -0,0 +1,49 @@
+from archo.schemas.architecture import ArchitectureResponse
+
+
+def generate_mermaid(data: ArchitectureResponse) -> str:
+    """Convert architecture JSON into a high-level Mermaid diagram string."""
+    name = data.service_name
+    language = data.language
+    framework = data.framework
+    databases = data.databases or []
+    outbound = data.outbound_calls or []
+
+    lines = ["graph LR"]
+    framework_and_language = f"{framework} / {language}" if framework != "none" else language
+    lines.append(f'    {name}["{name}<br>({framework_and_language})"]')
+    lines.append("")
+
+    for db in databases:
+        node_id = db.type.replace(" ", "_")
+        label = f"{db.type}<br>({', '.join(db.collections_or_tables)})" if db.collections_or_tables else db.type
+        lines.append(f'    {node_id}[("{label}")]')
+
+    for call in outbound:
+        node_id = call.target_service.replace(" ", "_").replace("-", "_")
+        lines.append(f'    {node_id}["{call.target_service}"]')
+
+    lines.append("")
+    # lines.append(f"    client --> {name}")
+
+    for db in databases:
+        node_id = db.type.replace(" ", "_")
+        lines.append(f"    {name} --> {node_id}")
+
+    for call in outbound:
+        node_id = call.target_service.replace(" ", "_").replace("-", "_")
+        lines.append(f"    {name} --> {node_id}")
+
+    return "\n".join(lines) + "\n"
+
+
+def write_mermaid(data: ArchitectureResponse, output_path: str = "ARCHITECTURE.mermaid") -> None:
+    """Write the Mermaid diagram to a file."""
+    print(f"Generating {output_path}...")
+    content = generate_mermaid(data)
+    try:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        print(f"Done — {output_path} written.")
+    except Exception as e:
+        raise RuntimeError(f"Failed to write {output_path}: {e}")

archo-0.1.0/src/archo/output/output_generator.py

@@ -0,0 +1,17 @@
+from archo.output.mermaid_generator import generate_mermaid
+from archo.output.markdown_generator import generate_markdown
+from archo.schemas.architecture import ArchitectureResponse
+
+
+def write_output(data: ArchitectureResponse, output_path: str = "ARCHO.md") -> None:
+    """Write the combined Mermaid diagram and markdown detail to a single file."""
+    print(f"Generating {output_path}...")
+    mermaid = generate_mermaid(data)
+    markdown = generate_markdown(data)
+    content = "```mermaid\n" + mermaid + "```\n\n" + markdown
+    try:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(content)
+        print(f"Done — {output_path} written.")
+    except Exception as e:
+        raise RuntimeError(f"Failed to write {output_path}: {e}")

archo-0.1.0/src/archo/schemas/architecture.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel
+
+class Route(BaseModel):
+    method: str
+    path: str
+
+class OutboundCall(BaseModel):
+    target_service: str
+    via: str
+
+class Pubsub(BaseModel):
+    subscribes: list[str]
+    publishes: list[str]
+
+class Database(BaseModel):
+    type: str
+    collections_or_tables: list[str]
+
+class ArchitectureResponse(BaseModel):
+    service_name: str
+    language: str
+    framework: str
+    routes: list[Route]
+    outbound_calls: list[OutboundCall] | None = None
+    pubsub: Pubsub | None = None
+    databases: list[Database] | None = None

archo-0.1.0/src/archo.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: archo
+Version: 0.1.0
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.24.0
+Requires-Dist: platformdirs>=4.9.4
+Requires-Dist: tomli_w>=1.2.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"

archo-0.1.0/src/archo.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+README.md
+pyproject.toml
+src/archo/__init__.py
+src/archo/config.py
+src/archo/main.py
+src/archo.egg-info/PKG-INFO
+src/archo.egg-info/SOURCES.txt
+src/archo.egg-info/dependency_links.txt
+src/archo.egg-info/entry_points.txt
+src/archo.egg-info/requires.txt
+src/archo.egg-info/top_level.txt
+src/archo/collector/__init__.py
+src/archo/collector/file_collector.py
+src/archo/llm/__init__.py
+src/archo/llm/llm_client.py
+src/archo/llm/prompt.py
+src/archo/llm/providers/__init__.py
+src/archo/llm/providers/anthropic.py
+src/archo/llm/providers/llm_base.py
+src/archo/llm/providers/ollama.py
+src/archo/llm/providers/openai.py
+src/archo/output/markdown_generator.py
+src/archo/output/mermaid_generator.py
+src/archo/output/output_generator.py
+src/archo/schemas/architecture.py

archo-0.1.0/src/archo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

archo-0.1.0/src/archo.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+archo = archo.main:app

archo-0.1.0/src/archo.egg-info/requires.txt

@@ -0,0 +1,9 @@
+anthropic>=0.84.0
+python-dotenv>=1.2.2
+pydantic>=2.0
+typer>=0.24.0
+platformdirs>=4.9.4
+tomli_w>=1.2.0
+
+[openai]
+openai>=1.0

archo-0.1.0/src/archo.egg-info/top_level.txt

@@ -0,0 +1 @@
+archo