Add example readme maker

.gitignore

@@ -6,6 +6,8 @@ dist/
 wheels/
 *.egg-info
 
+.env
+
 # Virtual environments
 .venv
 

examples/readme_maker/README.md

@@ -0,0 +1,50 @@
+# Pydantic AI README Maker
+
+This agent is built using the `pydantic-ai` framework and leverages GitHub's MCP server to automatically generate READMEs for your repositories.
+
+## Key Features
+
+* Generate READMEs for a target repository
+* Use another's repo README as a template
+* Automatically open a pull request with the generated README on your target repository
+
+## Getting Started
+
+### Step 1: Set Up Your Environment
+```bash
+uv venv
+source venv/bin/activate
+```
+
+### Step 2: Install dependencies
+```bash
+uv sync --group all
+```
+
+### Step 3: Initialize a new MCPD project and add the GitHub MCP server
+```bash
+mcpd init
+mcpd add github
+```
+
+### Step 4: Configure your agent's API key and the GitHub token for the MCP server
+```bash
+export <PROVIDER>_API_KEY=your_<provider>_api_key # Required for the Agent, the example code currently uses Mistral.
+mcpd config env set github GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token # Required by the GitHub MCP server
+```
+
+### Step 5: Start the MCPD server
+```bash
+mcpd daemon
+```
+
+### Step 6: In another terminal, run the agent
+```bash
+uv run readme_maker.py
+```
+
+### (Optional): Run mcpd daemon in debug mode to see the server logs:
+```bash
+mcpd daemon --log-level=DEBUG --log-path=$(pwd)/mcpd.log
+tail -f mcpd.log # Run in another terminal window
+```

examples/readme_maker/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "example-readme-maker"
+version = "0.0.1"
+description = "Example using mcpd with PydanticAI to create GitHub PRs for updated READMEs"
+readme = "README.md"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.32.4",
+    "mcpd_sdk",
+    "pydantic-ai>=0.3.7",
+]
+
+[dependency-groups]
+dev = [
+    { include-group = "lint" },
+    { include-group = "tests" },
+    "debugpy>=1.8.14",
+]
+
+lint = [
+    "pre-commit>=4.2.0",
+    "ruff>=0.11.13",
+]
+
+tests = [
+    "pytest>=8.3.5",
+]
+
+all = [
+    { include-group = "dev" },
+    { include-group = "lint" },
+    { include-group = "tests" },
+]
+
+[tool.uv.sources]
+mcpd_sdk = { path = "../..", editable = true }
+
+[tool.ruff]
+fix = true
+line-length=120
+
+[tool.ruff.lint]
+select = ["I"]

examples/readme_maker/readme_maker.py

@@ -0,0 +1,72 @@
+from dotenv import load_dotenv
+from mcpd_sdk import McpdClient
+from pydantic_ai import Agent
+
+load_dotenv()  # Load the API key for the agent (using Mistral in this case)
+
+agent_model = "mistral:mistral-large-2411"
+
+# Connect to the MCPD server to enable the agent access the tools running on it.
+client = McpdClient(api_endpoint="http://localhost:8090")
+
+agent = Agent(
+    agent_model,
+    tools=client.agent_tools(),
+    system_prompt="You must use the available GitHub tool to search for a README file, "
+    "create a new branch, create a new README file, and open a Pull Request.",
+)
+
+target_repo = input(
+    "Enter the target GitHub repository (in the format owner/repo-name) where the new README should be created: "
+)
+
+input_repo_readme = input(
+    "(Optional) Enter the GitHub repository (in the format owner/repo-name) to use its README as a template (press Enter to let the LLM define the structure): "
+)
+
+prompt = f"""
+Create a new README file for the target repository ({target_repo}).
+
+If a template README file from an original repository ({input_repo_readme}) is provided:
+
+- Template Utilization: Use the structure and style of the original README file as a guide.
+- Content Adaptation: Modify the content to accurately describe the target repository. 
+This step requires analyzing the entire codebase of the target repository ({target_repo}) 
+to understand its functionality, features, and any other relevant details that should be included in the README.
+
+If no template README file is provided:
+
+README Creation: Generate a high-quality README file from scratch, including relevant sections such as:
+-Project description and overview
+-Installation and setup instructions
+-Usage examples
+-Configuration options
+-Contributing guidelines
+-License information
+-Acknowledgements (if applicable)
+
+To create the README, analyze the entire codebase of the target repository ({target_repo}) 
+to understand its functionality, features, and any other relevant details.
+
+After creating the new README file:
+
+1. Branch Creation: Create a new branch in the target repository ({target_repo}) to hold the changes.
+2. Commit: Commit the newly generated README file to this branch with a concise and descriptive
+ commit message that clearly indicates the addition of the new README.
+3. Pull Request (PR) Creation: Open a Pull Request against the main branch of the target
+ repository, including the new README file.
+4. PR Description: In the Pull Request description, mention that the README was generated 
+by an AI agent of the model {agent_model}. If a template was used, include a link to 
+the original README template ({input_repo_readme}) used for generating the new README.
+
+When providing code snippets for this task, follow the guidelines for code modifications:
+
+- Always specify the language and file name in the info string of code blocks (e.g., python src/main.py).
+- For code modifications, use concise snippets that highlight the necessary changes, with abbreviated placeholders for unmodified sections.
+- When editing existing files, restate the relevant function or class and use 'lazy' comments to omit unmodified portions.
+
+Please provide a concise explanation of the changes made unless explicitly asked for code only
+"""
+
+agent_trace = agent.run_sync(prompt)
+print(agent_trace.output)