github-kb 0.1.1__tar.gz

github_kb-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gonzalo Ayuso
+
+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.

github_kb-0.1.1/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: github-kb
+Version: 0.1.1
+Summary: Ask questions about a GitHub repository with Strands Agents and AWS Bedrock
+License: MIT
+License-File: LICENSE
+Keywords: github,ai,agents,bedrock,cli,developer-tools
+Author: Gonzalo Ayuso
+Author-email: gonzalo123@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Dist: boto3 (>=1.42.78,<2.0.0)
+Requires-Dist: click (>=8.3.1,<9.0.0)
+Requires-Dist: pydantic (>=2.12.3,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.13.1,<3.0.0)
+Requires-Dist: python-dotenv (>=1.2.2,<2.0.0)
+Requires-Dist: rich (>=14.3.0,<15.0.0)
+Requires-Dist: strands-agents (>=1.34.1,<2.0.0)
+Project-URL: Documentation, https://github.com/gonzalo123/github.kb#readme
+Project-URL: Homepage, https://github.com/gonzalo123/github.kb
+Project-URL: Repository, https://github.com/gonzalo123/github.kb
+Description-Content-Type: text/markdown
+
+# What if you could ask questions to any GitHub repository? Building a repository-aware AI agent with Python, Strands Agents, and Bedrock
+
+Sometimes we land on an unfamiliar GitHub repository and the first problem is not writing code. The real problem is understanding the project fast enough. Is this a REST API? Where are the entrypoints? How is the application wired? Are there obvious risks in the codebase? If the repository is big enough, answering those questions manually is slow and boring.
+
+That's just my PoC. An interactive command-line application that can inspect any public GitHub repository and answer questions about it.
+
+![logo](assets/logo.png)
+
+I have the feeling this workflow should exist natively on GitHub. Once repositories become large enough, being able to ask architecture, audit, or API questions feels like a natural evolution of code search and Copilot. Maybe the reason it does not exist yet is cost, scope, or product complexity. In the meantime, a CLI-first open source approach feels like a good place to start: simple, scriptable, hackable, and based on bring-your-own-model credentials so each user keeps control of their own usage and billing.
+
+The idea is simple. We give a GitHub repository to a CLI application. The CLI creates a local checkout, exposes a small set of repository-aware tools to a Strands Agent, and lets the agent inspect the project with AWS Bedrock. Because the agent can list directories, search code and read files, we can ask practical questions such as:
+
+- Explain how the project works
+- Audit the codebase looking for risks
+- List the API endpoints
+- Describe the execution flow of a specific module
+
+This is not a vector database project and it is not a RAG pipeline. It is a much simpler approach. We let the agent explore the repository directly, file by file, using tools.
+
+## The architecture
+
+The flow is straightforward:
+
+1. The user calls the CLI with a GitHub repository.
+2. The repository is cloned into a local cache.
+3. A Strands Agent is created with a Bedrock model.
+4. The agent receives a system prompt plus four tools:
+   `get_directory_tree`, `list_directory`, `search_code` and `read_file`.
+5. The agent inspects the repository and returns the final answer in Markdown.
+
+This is enough for a surprising number of use cases. If the system prompt is focused on architecture, the answer becomes an explanation. If the prompt is focused on risk, the answer becomes a code audit. If the prompt is focused on HTTP routes, the answer becomes an API inventory.
+
+## Project structure
+
+I like to keep configuration in `settings.py`. It is a pattern I borrowed years ago from Django and I still use it in small prototypes because it keeps things simple:
+
+```text
+src/
+└── github_kb/
+    ├── cli.py
+    ├── settings.py
+    ├── commands/
+    │   ├── ask.py
+    │   ├── audit.py
+    │   ├── chat.py
+    │   ├── endpoints.py
+    │   └── explain.py
+    ├── lib/
+    │   ├── agent.py
+    │   ├── github.py
+    │   ├── models.py
+    │   ├── prompts.py
+    │   ├── repository.py
+    │   └── ui.py
+    └── env/
+        └── local/
+            └── .env.example
+```
+
+The responsibilities are small and explicit:
+
+- `github_kb/commands/` contains the Click commands.
+- `github_kb/lib/github.py` resolves the GitHub repository and manages the local checkout.
+- `github_kb/lib/repository.py` contains the repository exploration logic used by the agent tools.
+- `github_kb/lib/agent.py` wires Strands Agents with AWS Bedrock.
+- `github_kb/lib/prompts.py` keeps the system prompt and the task-specific prompts in one place.
+
+## Why this works
+
+Large repositories are difficult because we rarely need the whole repository at once. We normally need a guided exploration strategy. A tree view helps us identify the shape of the project. Search helps us jump to the interesting files. Reading files gives us the final confirmation.
+
+That sequence maps very well to tool-based agents.
+
+Instead of trying to send the whole repository in one prompt, the model can progressively inspect only the relevant parts. It is cheaper, easier to reason about, and much closer to how we inspect an unknown codebase ourselves.
+
+## Install
+
+The intended installation flow is:
+
+```bash
+pipx install github-kb
+```
+
+## Quick start
+
+The happy path should look like this:
+
+```bash
+aws sso login --profile sandbox
+AWS_PROFILE=sandbox AWS_REGION=us-west-2 github-kb doctor
+AWS_PROFILE=sandbox AWS_REGION=us-west-2 github-kb chat gonzalo123/autofix
+```
+
+The CLI is designed to work out of the box with the standard AWS credential chain. That means it can use:
+
+- `AWS_PROFILE`
+- `AWS_REGION`
+- `aws sso login`
+- regular access keys if they are already configured in the environment
+
+You can also override the runtime explicitly with CLI flags such as `--aws-profile`, `--region`, and `--model`.
+
+## Usage
+
+Now we can ask questions:
+
+```bash
+github-kb ask gonzalo123/autofix "How does the automated fix flow work?"
+github-kb chat gonzalo123/autofix
+github-kb explain gonzalo123/autofix --topic architecture
+github-kb audit gonzalo123/autofix --focus github
+github-kb endpoints gonzalo123/autofix
+github-kb doctor
+```
+
+If we want to keep the same conversation alive across multiple questions in one terminal session:
+
+```bash
+github-kb chat gonzalo123/autofix
+```
+
+It also accepts full GitHub URLs:
+
+```bash
+github-kb ask https://github.com/gonzalo123/autofix "Where is the application bootstrapped?"
+```
+
+If we want to refresh the local cache:
+
+```bash
+github-kb audit gonzalo123/autofix --refresh
+```
+
+We can also pass the AWS runtime explicitly:
+
+```bash
+github-kb chat gonzalo123/autofix --aws-profile sandbox --region us-west-2
+github-kb ask gonzalo123/autofix "Explain the architecture" --model us.anthropic.claude-sonnet-4-20250514-v1:0
+```
+
+## Development
+
+For local development:
+
+```bash
+poetry install
+cp src/github_kb/env/local/.env.example src/github_kb/env/local/.env
+poetry run pytest -q
+poetry run github-kb --help
+```
+
+For local packaging tests:
+
+```bash
+poetry build
+pipx install --force dist/github_kb-0.1.0-py3-none-any.whl
+github-kb --help
+```
+
+For publishing, see [RELEASING.md](RELEASING.md).
+
+## Demo screenshots
+
+Here are a few real screenshots generated against one of my own repositories, [`gonzalo123/autofix`](https://github.com/gonzalo123/autofix).
+
+The screenshots below are embedded as PNG files:
+
+### `explain`
+
+![Explain demo](assets/demo-explain.png)
+
+### `endpoints`
+
+![Endpoints demo](assets/demo-endpoints.png)
+
+### `audit`
+
+![Audit demo](assets/demo-audit.png)
+
+## A couple of notes
+
+This is still a PoC. The goal is not to build a perfect repository analysis platform. The goal is to validate a simple idea: an agent with a tiny set of well-chosen tools can already be useful for code understanding.
+
+There are several obvious next steps:
+
+- add more repository-aware tools
+- persist analysis sessions
+- summarize previous findings before starting a new question
+- support GitHub authentication for private repositories
+- add specialized prompts for security reviews or framework-specific inspections
+
+Even in its current state, it is already a nice example of how tool-based agents can help with a very real developer problem.
+

github_kb-0.1.1/README.md

@@ -0,0 +1,192 @@
+# What if you could ask questions to any GitHub repository? Building a repository-aware AI agent with Python, Strands Agents, and Bedrock
+
+Sometimes we land on an unfamiliar GitHub repository and the first problem is not writing code. The real problem is understanding the project fast enough. Is this a REST API? Where are the entrypoints? How is the application wired? Are there obvious risks in the codebase? If the repository is big enough, answering those questions manually is slow and boring.
+
+That's just my PoC. An interactive command-line application that can inspect any public GitHub repository and answer questions about it.
+
+![logo](assets/logo.png)
+
+I have the feeling this workflow should exist natively on GitHub. Once repositories become large enough, being able to ask architecture, audit, or API questions feels like a natural evolution of code search and Copilot. Maybe the reason it does not exist yet is cost, scope, or product complexity. In the meantime, a CLI-first open source approach feels like a good place to start: simple, scriptable, hackable, and based on bring-your-own-model credentials so each user keeps control of their own usage and billing.
+
+The idea is simple. We give a GitHub repository to a CLI application. The CLI creates a local checkout, exposes a small set of repository-aware tools to a Strands Agent, and lets the agent inspect the project with AWS Bedrock. Because the agent can list directories, search code and read files, we can ask practical questions such as:
+
+- Explain how the project works
+- Audit the codebase looking for risks
+- List the API endpoints
+- Describe the execution flow of a specific module
+
+This is not a vector database project and it is not a RAG pipeline. It is a much simpler approach. We let the agent explore the repository directly, file by file, using tools.
+
+## The architecture
+
+The flow is straightforward:
+
+1. The user calls the CLI with a GitHub repository.
+2. The repository is cloned into a local cache.
+3. A Strands Agent is created with a Bedrock model.
+4. The agent receives a system prompt plus four tools:
+   `get_directory_tree`, `list_directory`, `search_code` and `read_file`.
+5. The agent inspects the repository and returns the final answer in Markdown.
+
+This is enough for a surprising number of use cases. If the system prompt is focused on architecture, the answer becomes an explanation. If the prompt is focused on risk, the answer becomes a code audit. If the prompt is focused on HTTP routes, the answer becomes an API inventory.
+
+## Project structure
+
+I like to keep configuration in `settings.py`. It is a pattern I borrowed years ago from Django and I still use it in small prototypes because it keeps things simple:
+
+```text
+src/
+└── github_kb/
+    ├── cli.py
+    ├── settings.py
+    ├── commands/
+    │   ├── ask.py
+    │   ├── audit.py
+    │   ├── chat.py
+    │   ├── endpoints.py
+    │   └── explain.py
+    ├── lib/
+    │   ├── agent.py
+    │   ├── github.py
+    │   ├── models.py
+    │   ├── prompts.py
+    │   ├── repository.py
+    │   └── ui.py
+    └── env/
+        └── local/
+            └── .env.example
+```
+
+The responsibilities are small and explicit:
+
+- `github_kb/commands/` contains the Click commands.
+- `github_kb/lib/github.py` resolves the GitHub repository and manages the local checkout.
+- `github_kb/lib/repository.py` contains the repository exploration logic used by the agent tools.
+- `github_kb/lib/agent.py` wires Strands Agents with AWS Bedrock.
+- `github_kb/lib/prompts.py` keeps the system prompt and the task-specific prompts in one place.
+
+## Why this works
+
+Large repositories are difficult because we rarely need the whole repository at once. We normally need a guided exploration strategy. A tree view helps us identify the shape of the project. Search helps us jump to the interesting files. Reading files gives us the final confirmation.
+
+That sequence maps very well to tool-based agents.
+
+Instead of trying to send the whole repository in one prompt, the model can progressively inspect only the relevant parts. It is cheaper, easier to reason about, and much closer to how we inspect an unknown codebase ourselves.
+
+## Install
+
+The intended installation flow is:
+
+```bash
+pipx install github-kb
+```
+
+## Quick start
+
+The happy path should look like this:
+
+```bash
+aws sso login --profile sandbox
+AWS_PROFILE=sandbox AWS_REGION=us-west-2 github-kb doctor
+AWS_PROFILE=sandbox AWS_REGION=us-west-2 github-kb chat gonzalo123/autofix
+```
+
+The CLI is designed to work out of the box with the standard AWS credential chain. That means it can use:
+
+- `AWS_PROFILE`
+- `AWS_REGION`
+- `aws sso login`
+- regular access keys if they are already configured in the environment
+
+You can also override the runtime explicitly with CLI flags such as `--aws-profile`, `--region`, and `--model`.
+
+## Usage
+
+Now we can ask questions:
+
+```bash
+github-kb ask gonzalo123/autofix "How does the automated fix flow work?"
+github-kb chat gonzalo123/autofix
+github-kb explain gonzalo123/autofix --topic architecture
+github-kb audit gonzalo123/autofix --focus github
+github-kb endpoints gonzalo123/autofix
+github-kb doctor
+```
+
+If we want to keep the same conversation alive across multiple questions in one terminal session:
+
+```bash
+github-kb chat gonzalo123/autofix
+```
+
+It also accepts full GitHub URLs:
+
+```bash
+github-kb ask https://github.com/gonzalo123/autofix "Where is the application bootstrapped?"
+```
+
+If we want to refresh the local cache:
+
+```bash
+github-kb audit gonzalo123/autofix --refresh
+```
+
+We can also pass the AWS runtime explicitly:
+
+```bash
+github-kb chat gonzalo123/autofix --aws-profile sandbox --region us-west-2
+github-kb ask gonzalo123/autofix "Explain the architecture" --model us.anthropic.claude-sonnet-4-20250514-v1:0
+```
+
+## Development
+
+For local development:
+
+```bash
+poetry install
+cp src/github_kb/env/local/.env.example src/github_kb/env/local/.env
+poetry run pytest -q
+poetry run github-kb --help
+```
+
+For local packaging tests:
+
+```bash
+poetry build
+pipx install --force dist/github_kb-0.1.0-py3-none-any.whl
+github-kb --help
+```
+
+For publishing, see [RELEASING.md](RELEASING.md).
+
+## Demo screenshots
+
+Here are a few real screenshots generated against one of my own repositories, [`gonzalo123/autofix`](https://github.com/gonzalo123/autofix).
+
+The screenshots below are embedded as PNG files:
+
+### `explain`
+
+![Explain demo](assets/demo-explain.png)
+
+### `endpoints`
+
+![Endpoints demo](assets/demo-endpoints.png)
+
+### `audit`
+
+![Audit demo](assets/demo-audit.png)
+
+## A couple of notes
+
+This is still a PoC. The goal is not to build a perfect repository analysis platform. The goal is to validate a simple idea: an agent with a tiny set of well-chosen tools can already be useful for code understanding.
+
+There are several obvious next steps:
+
+- add more repository-aware tools
+- persist analysis sessions
+- summarize previous findings before starting a new question
+- support GitHub authentication for private repositories
+- add specialized prompts for security reviews or framework-specific inspections
+
+Even in its current state, it is already a nice example of how tool-based agents can help with a very real developer problem.

github_kb-0.1.1/pyproject.toml

@@ -0,0 +1,47 @@
+[tool.poetry]
+name = "github-kb"
+version = "0.1.1"
+description = "Ask questions about a GitHub repository with Strands Agents and AWS Bedrock"
+license = "MIT"
+authors = ["Gonzalo Ayuso <gonzalo123@gmail.com>"]
+readme = "README.md"
+homepage = "https://github.com/gonzalo123/github.kb"
+repository = "https://github.com/gonzalo123/github.kb"
+documentation = "https://github.com/gonzalo123/github.kb#readme"
+keywords = ["github", "ai", "agents", "bedrock", "cli", "developer-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+packages = [{include = "github_kb", from = "src"}]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<4.0"
+boto3 = "^1.42.78"
+click = "^8.3.1"
+pydantic = "^2.12.3"
+pydantic-settings = "^2.13.1"
+python-dotenv = "^1.2.2"
+rich = "^14.3.0"
+strands-agents = "^1.34.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.2"
+
+[tool.poetry.scripts]
+github-kb = "github_kb.cli:cli"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

github_kb-0.1.1/src/github_kb/__init__.py

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

github_kb-0.1.1/src/github_kb/__main__.py

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

github_kb-0.1.1/src/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-0.1.1/src/github_kb/commands/__init__.py

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

github_kb-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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))