github-kb 0.1.1__py3-none-any.whl

github_kb/__init__.py

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

github_kb/__main__.py

@@ -0,0 +1,5 @@
+from github_kb.cli import cli
+
+
+if __name__ == "__main__":
+    cli()

github_kb/cli.py

@@ -0,0 +1,25 @@
+import click
+
+from github_kb.commands.ask import ask_command
+from github_kb.commands.audit import audit_command
+from github_kb.commands.chat import chat_command
+from github_kb.commands.doctor import doctor_command
+from github_kb.commands.endpoints import endpoints_command
+from github_kb.commands.explain import explain_command
+
+
+@click.group()
+def cli() -> None:
+    """Ask questions about a GitHub repository using Strands Agents and AWS Bedrock."""
+
+
+cli.add_command(ask_command)
+cli.add_command(audit_command)
+cli.add_command(chat_command)
+cli.add_command(doctor_command)
+cli.add_command(endpoints_command)
+cli.add_command(explain_command)
+
+
+if __name__ == "__main__":
+    cli()

github_kb/commands/__init__.py

@@ -0,0 +1 @@
+# Commands package.

github_kb/commands/ask.py

@@ -0,0 +1,32 @@
+import click
+
+from github_kb.commands.common import join_parts, run_prompt, runtime_options
+
+
+@click.command(name="ask")
+@click.argument("repository")
+@click.argument("question", nargs=-1, required=True)
+@click.option("--ref", default=None, help="Git branch, tag or commit to inspect.")
+@click.option("--refresh", is_flag=True, help="Refresh the cached local checkout.")
+@runtime_options
+def ask_command(
+    repository: str,
+    question: tuple[str, ...],
+    ref: str | None,
+    refresh: bool,
+    aws_profile: str | None,
+    region: str | None,
+    model: str | None,
+) -> None:
+    """Ask an open question about a GitHub repository."""
+
+    run_prompt(
+        repository,
+        join_parts(question),
+        title="Answer",
+        ref=ref,
+        refresh=refresh,
+        aws_profile=aws_profile,
+        region=region,
+        model=model,
+    )

github_kb/commands/audit.py

@@ -0,0 +1,33 @@
+import click
+
+from github_kb.commands.common import run_prompt, runtime_options
+from github_kb.lib.prompts import build_audit_prompt
+
+
+@click.command(name="audit")
+@click.argument("repository")
+@click.option("--focus", default=None, help="Optional area to focus the audit on.")
+@click.option("--ref", default=None, help="Git branch, tag or commit to inspect.")
+@click.option("--refresh", is_flag=True, help="Refresh the cached local checkout.")
+@runtime_options
+def audit_command(
+    repository: str,
+    focus: str | None,
+    ref: str | None,
+    refresh: bool,
+    aws_profile: str | None,
+    region: str | None,
+    model: str | None,
+) -> None:
+    """Run a code audit against the repository."""
+
+    run_prompt(
+        repository,
+        build_audit_prompt(focus=focus),
+        title="Audit",
+        ref=ref,
+        refresh=refresh,
+        aws_profile=aws_profile,
+        region=region,
+        model=model,
+    )

github_kb/commands/chat.py

@@ -0,0 +1,60 @@
+import click
+
+from github_kb.commands.common import prepare_agent, runtime_options
+from github_kb.lib.ui import get_console, print_repository_panel, print_result
+
+EXIT_COMMANDS = {"exit", "quit", "/exit", "/quit", ":q", "q"}
+
+
+def is_exit_command(value: str) -> bool:
+    return value.strip().lower() in EXIT_COMMANDS
+
+
+@click.command(name="chat")
+@click.argument("repository")
+@click.option("--ref", default=None, help="Git branch, tag or commit to inspect.")
+@click.option("--refresh", is_flag=True, help="Refresh the cached local checkout.")
+@runtime_options
+def chat_command(
+    repository: str,
+    ref: str | None,
+    refresh: bool,
+    aws_profile: str | None,
+    region: str | None,
+    model: str | None,
+) -> None:
+    """Start a conversational session about a GitHub repository."""
+
+    console = get_console()
+    repository_context, agent = prepare_agent(
+        repository,
+        ref=ref,
+        refresh=refresh,
+        aws_profile=aws_profile,
+        region=region,
+        model=model,
+    )
+    print_repository_panel(repository_context)
+    console.print("Interactive mode. Type your question or `/exit` to finish.\n")
+
+    while True:
+        try:
+            question = console.input("[bold cyan]> [/]").strip()
+        except (EOFError, KeyboardInterrupt):
+            console.print("\nSession closed.")
+            break
+
+        if not question:
+            continue
+
+        if is_exit_command(question):
+            console.print("Session closed.")
+            break
+
+        try:
+            with console.status("Thinking with Bedrock...", spinner="dots"):
+                result = agent(question)
+        except Exception as error:
+            raise click.ClickException(str(error)) from error
+
+        print_result("Answer", str(result))

github_kb/commands/common.py

@@ -0,0 +1,109 @@
+from collections.abc import Sequence
+from functools import wraps
+
+import click
+from strands import Agent
+
+from github_kb.lib.agent import create_agent
+from github_kb.lib.github import ensure_repository, parse_repository
+from github_kb.lib.models import RepositoryContext
+from github_kb.lib.repository import RepositoryExplorer
+from github_kb.lib.ui import get_console, print_repository_panel, print_result
+from github_kb.settings import resolve_settings
+
+
+def runtime_options(function):
+    @click.option(
+        "--aws-profile",
+        default=None,
+        help="AWS profile name to use. Falls back to AWS_PROFILE if unset.",
+    )
+    @click.option(
+        "--region",
+        default=None,
+        help="AWS region for Bedrock. Falls back to AWS_REGION if unset.",
+    )
+    @click.option(
+        "--model",
+        default=None,
+        help="Bedrock model id. Falls back to BEDROCK_MODEL_ID if unset.",
+    )
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        return function(*args, **kwargs)
+
+    return wrapper
+
+
+def join_parts(parts: Sequence[str]) -> str:
+    return " ".join(part for part in parts if part).strip()
+
+
+def run_prompt(
+    repository: str,
+    prompt: str,
+    *,
+    title: str,
+    ref: str | None = None,
+    refresh: bool = False,
+    aws_profile: str | None = None,
+    region: str | None = None,
+    model: str | None = None,
+) -> None:
+    repository_context, agent = prepare_agent(
+        repository,
+        ref=ref,
+        refresh=refresh,
+        aws_profile=aws_profile,
+        region=region,
+        model=model,
+    )
+    print_repository_panel(repository_context)
+
+    console = get_console()
+    try:
+        with console.status("Thinking with Bedrock...", spinner="dots"):
+            result = agent(prompt)
+    except Exception as error:
+        raise click.ClickException(str(error)) from error
+
+    print_result(title, str(result))
+
+
+def prepare_agent(
+    repository: str,
+    *,
+    ref: str | None = None,
+    refresh: bool = False,
+    aws_profile: str | None = None,
+    region: str | None = None,
+    model: str | None = None,
+) -> tuple[RepositoryContext, Agent]:
+    settings = resolve_settings(
+        aws_profile=aws_profile,
+        aws_region=region,
+        bedrock_model_id=model,
+    )
+    console = get_console()
+
+    try:
+        repo_reference = parse_repository(repository, ref=ref)
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+
+    try:
+        with console.status(f"Preparing {repo_reference.slug}...", spinner="dots"):
+            repository_context = ensure_repository(
+                repo_reference,
+                settings=settings,
+                refresh=refresh,
+            )
+            explorer = RepositoryExplorer(
+                root_path=repository_context.local_path,
+                settings=settings,
+            )
+            agent = create_agent(explorer, settings=settings)
+    except Exception as error:
+        raise click.ClickException(str(error)) from error
+
+    return repository_context, agent

github_kb/commands/doctor.py

@@ -0,0 +1,39 @@
+import click
+from rich.table import Table
+
+from github_kb.commands.common import runtime_options
+from github_kb.lib.doctor import run_diagnostics
+from github_kb.lib.ui import get_console
+from github_kb.settings import resolve_settings
+
+
+@click.command(name="doctor")
+@runtime_options
+def doctor_command(
+    aws_profile: str | None,
+    region: str | None,
+    model: str | None,
+) -> None:
+    """Validate the local runtime, AWS credentials and Bedrock access."""
+
+    console = get_console()
+    settings = resolve_settings(
+        aws_profile=aws_profile,
+        aws_region=region,
+        bedrock_model_id=model,
+    )
+    results = run_diagnostics(settings)
+
+    table = Table(title="github-kb doctor")
+    table.add_column("Check")
+    table.add_column("Status")
+    table.add_column("Details")
+
+    for result in results:
+        status = "OK" if result.ok else "FAIL"
+        table.add_row(result.name, status, result.message)
+
+    console.print(table)
+
+    if not all(result.ok for result in results):
+        raise click.ClickException("One or more doctor checks failed.")

github_kb/commands/endpoints.py

@@ -0,0 +1,31 @@
+import click
+
+from github_kb.commands.common import run_prompt, runtime_options
+from github_kb.lib.prompts import build_endpoints_prompt
+
+
+@click.command(name="endpoints")
+@click.argument("repository")
+@click.option("--ref", default=None, help="Git branch, tag or commit to inspect.")
+@click.option("--refresh", is_flag=True, help="Refresh the cached local checkout.")
+@runtime_options
+def endpoints_command(
+    repository: str,
+    ref: str | None,
+    refresh: bool,
+    aws_profile: str | None,
+    region: str | None,
+    model: str | None,
+) -> None:
+    """List the API endpoints found in the repository."""
+
+    run_prompt(
+        repository,
+        build_endpoints_prompt(),
+        title="Endpoints",
+        ref=ref,
+        refresh=refresh,
+        aws_profile=aws_profile,
+        region=region,
+        model=model,
+    )

github_kb/commands/explain.py

@@ -0,0 +1,33 @@
+import click
+
+from github_kb.commands.common import run_prompt, runtime_options
+from github_kb.lib.prompts import build_explain_prompt
+
+
+@click.command(name="explain")
+@click.argument("repository")
+@click.option("--topic", default=None, help="Specific topic, module or flow to explain.")
+@click.option("--ref", default=None, help="Git branch, tag or commit to inspect.")
+@click.option("--refresh", is_flag=True, help="Refresh the cached local checkout.")
+@runtime_options
+def explain_command(
+    repository: str,
+    topic: str | None,
+    ref: str | None,
+    refresh: bool,
+    aws_profile: str | None,
+    region: str | None,
+    model: str | None,
+) -> None:
+    """Explain how the repository works."""
+
+    run_prompt(
+        repository,
+        build_explain_prompt(topic=topic),
+        title="Explanation",
+        ref=ref,
+        refresh=refresh,
+        aws_profile=aws_profile,
+        region=region,
+        model=model,
+    )

github_kb/env/local/.env.example

@@ -0,0 +1,2 @@
+AWS_REGION=us-west-2
+BEDROCK_MODEL_ID=us.anthropic.claude-sonnet-4-20250514-v1:0

github_kb/lib/__init__.py

@@ -0,0 +1 @@
+# Library package.

github_kb/lib/agent.py

@@ -0,0 +1,61 @@
+from boto3.session import Session
+from strands import Agent, tool
+from strands.models import BedrockModel
+
+from github_kb.lib.prompts import SYSTEM_PROMPT
+from github_kb.lib.repository import RepositoryExplorer
+from github_kb.settings import Settings, create_boto_session
+
+
+def create_agent(explorer: RepositoryExplorer, *, settings: Settings) -> Agent:
+    boto_session: Session = create_boto_session(settings)
+
+    return Agent(
+        model=BedrockModel(
+            boto_session=boto_session,
+            model_id=settings.bedrock_model_id,
+            region_name=settings.aws_region,
+        ),
+        tools=create_tools(explorer),
+        system_prompt=SYSTEM_PROMPT,
+    )
+
+
+def create_tools(explorer: RepositoryExplorer) -> list:
+    @tool
+    def get_directory_tree(path: str = ".", max_depth: int = 4) -> str:
+        """Return a tree view for a directory inside the repository."""
+
+        return explorer.get_directory_tree(path=path, max_depth=max_depth)
+
+    @tool
+    def list_directory(path: str = ".") -> str:
+        """List the files and directories inside a repository path."""
+
+        return explorer.list_directory(path=path)
+
+    @tool
+    def read_file(path: str, start_line: int = 1, end_line: int | None = None) -> str:
+        """Read a text file from the repository with line numbers."""
+
+        return explorer.read_file(
+            path=path,
+            start_line=start_line,
+            end_line=end_line,
+        )
+
+    @tool
+    def search_code(
+        query: str,
+        glob_pattern: str | None = None,
+        max_results: int = 20,
+    ) -> str:
+        """Search for text in repository files."""
+
+        return explorer.search_code(
+            query=query,
+            glob_pattern=glob_pattern,
+            max_results=max_results,
+        )
+
+    return [get_directory_tree, list_directory, read_file, search_code]

github_kb/lib/doctor.py

@@ -0,0 +1,115 @@
+import shutil
+
+from botocore.exceptions import BotoCoreError, ClientError, ProfileNotFound
+from pydantic import BaseModel
+
+from github_kb.settings import Settings, create_boto_session
+
+
+class DiagnosticResult(BaseModel):
+    name: str
+    ok: bool
+    message: str
+
+
+def run_diagnostics(settings: Settings) -> list[DiagnosticResult]:
+    results = [
+        check_binary("git", settings.git_binary),
+        check_binary("ripgrep", settings.rg_binary),
+    ]
+    results.extend(check_aws(settings))
+    return results
+
+
+def check_binary(name: str, command: str) -> DiagnosticResult:
+    resolved = shutil.which(command)
+    if resolved:
+        return DiagnosticResult(name=name, ok=True, message=f"Found at {resolved}")
+    return DiagnosticResult(name=name, ok=False, message=f"Command not found: {command}")
+
+
+def check_aws(settings: Settings) -> list[DiagnosticResult]:
+    results: list[DiagnosticResult] = []
+
+    try:
+        session = create_boto_session(settings)
+    except ProfileNotFound as error:
+        return [
+            DiagnosticResult(
+                name="aws-profile",
+                ok=False,
+                message=str(error),
+            )
+        ]
+
+    profile_name = session.profile_name or settings.aws_profile or "default credential chain"
+    results.append(
+        DiagnosticResult(
+            name="aws-profile",
+            ok=True,
+            message=f"Using {profile_name}",
+        )
+    )
+
+    credentials = session.get_credentials()
+    if credentials is None:
+        results.append(
+            DiagnosticResult(
+                name="aws-credentials",
+                ok=False,
+                message="No AWS credentials found. Set AWS_PROFILE or configure the default AWS credential chain.",
+            )
+        )
+        return results
+
+    method = getattr(credentials, "method", "resolved")
+    results.append(
+        DiagnosticResult(
+            name="aws-credentials",
+            ok=True,
+            message=f"Resolved via {method}",
+        )
+    )
+
+    try:
+        identity = session.client("sts", region_name=settings.aws_region).get_caller_identity()
+        arn = identity.get("Arn", "unknown principal")
+        account = identity.get("Account", "unknown account")
+        results.append(
+            DiagnosticResult(
+                name="sts",
+                ok=True,
+                message=f"{arn} ({account})",
+            )
+        )
+    except (BotoCoreError, ClientError) as error:
+        results.append(
+            DiagnosticResult(
+                name="sts",
+                ok=False,
+                message=f"Unable to call STS: {error}",
+            )
+        )
+        return results
+
+    try:
+        session.client("bedrock", region_name=settings.aws_region).get_foundation_model(
+            modelIdentifier=settings.bedrock_model_id
+        )
+        results.append(
+            DiagnosticResult(
+                name="bedrock",
+                ok=True,
+                message=f"Model available: {settings.bedrock_model_id} in {settings.aws_region}",
+            )
+        )
+    except (BotoCoreError, ClientError) as error:
+        results.append(
+            DiagnosticResult(
+                name="bedrock",
+                ok=False,
+                message=f"Unable to validate model {settings.bedrock_model_id}: {error}",
+            )
+        )
+
+    return results

github_kb/lib/github.py

@@ -0,0 +1,111 @@
+from pathlib import Path
+import subprocess
+from urllib.parse import urlparse
+
+from github_kb.lib.models import GitHubRepositoryReference, RepositoryContext
+from github_kb.settings import Settings
+
+VALID_GITHUB_HOSTS = {"github.com", "www.github.com"}
+
+
+def parse_repository(value: str, ref: str | None = None) -> GitHubRepositoryReference:
+    raw_value = value.strip()
+    if not raw_value:
+        raise ValueError("Repository cannot be empty.")
+
+    detected_ref: str | None = None
+
+    if raw_value.startswith("http://") or raw_value.startswith("https://"):
+        parsed = urlparse(raw_value)
+        if parsed.netloc not in VALID_GITHUB_HOSTS:
+            raise ValueError("Only github.com repositories are supported in this PoC.")
+
+        parts = [part for part in parsed.path.split("/") if part]
+        if len(parts) < 2:
+            raise ValueError("Repository must include owner and name.")
+
+        owner = parts[0]
+        name = parts[1].removesuffix(".git")
+
+        if len(parts) >= 4 and parts[2] == "tree":
+            detected_ref = parts[3]
+    else:
+        parts = [part for part in raw_value.split("/") if part]
+        if len(parts) != 2:
+            raise ValueError("Repository must look like owner/name or a GitHub URL.")
+
+        owner = parts[0]
+        name = parts[1].removesuffix(".git")
+
+    return GitHubRepositoryReference(
+        owner=owner,
+        name=name,
+        clone_url=f"https://github.com/{owner}/{name}.git",
+        html_url=f"https://github.com/{owner}/{name}",
+        ref=ref or detected_ref,
+    )
+
+
+def ensure_repository(
+    repository: GitHubRepositoryReference,
+    *,
+    settings: Settings,
+    refresh: bool = False,
+) -> RepositoryContext:
+    cache_path = settings.repo_cache_path / repository.cache_key
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if not cache_path.exists():
+        _run_git(
+            settings,
+            ["clone", "--depth", "1", repository.clone_url, str(cache_path)],
+        )
+        _checkout_ref(cache_path, repository.ref, settings)
+    elif refresh:
+        _refresh_repository(cache_path, repository.ref, settings)
+
+    return RepositoryContext(repository=repository, local_path=cache_path)
+
+
+def _refresh_repository(path: Path, ref: str | None, settings: Settings) -> None:
+    if ref:
+        _run_git(settings, ["fetch", "--depth", "1", "origin", ref], cwd=path)
+        _run_git(settings, ["checkout", "--detach", "FETCH_HEAD"], cwd=path)
+        return
+
+    current_branch = _run_git(
+        settings,
+        ["rev-parse", "--abbrev-ref", "HEAD"],
+        cwd=path,
+    ).strip()
+    if current_branch == "HEAD":
+        current_branch = _run_git(
+            settings,
+            ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+            cwd=path,
+        ).removeprefix("origin/")
+    _run_git(settings, ["checkout", current_branch], cwd=path)
+    _run_git(settings, ["pull", "--ff-only", "origin", current_branch], cwd=path)
+
+
+def _checkout_ref(path: Path, ref: str | None, settings: Settings) -> None:
+    if not ref:
+        return
+
+    _run_git(settings, ["fetch", "--depth", "1", "origin", ref], cwd=path)
+    _run_git(settings, ["checkout", "--detach", "FETCH_HEAD"], cwd=path)
+
+
+def _run_git(settings: Settings, args: list[str], cwd: Path | None = None) -> str:
+    command = [settings.git_binary, *args]
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        message = completed.stderr.strip() or completed.stdout.strip() or "Unknown git error"
+        raise RuntimeError(message)
+    return completed.stdout.strip()