pkgq 0.2.0__tar.gz → 0.3.0__tar.gz

{pkgq-0.2.0 → pkgq-0.3.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pkgq",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Package Query - Find, create, and update package documentation for AI agents",
   "author": {
     "name": "Christophe VG",

{pkgq-0.2.0 → pkgq-0.3.0}/.gitignore

@@ -34,4 +34,7 @@ Thumbs.db
 
 # Local
 *.local.*
-.env
+.env
+
+# MCP Configuration (user-specific)
+.mcp.json

pkgq-0.3.0/HISTORY.md

@@ -0,0 +1,65 @@
+# pkgq Version History
+
+## 0.3.0 (2026-06-26)
+
+### New Features
+
+- **Yoker plugin support**: pkgq can now be loaded as a yoker plugin
+  - Exposes `find` tool for package documentation queries
+  - Includes `create` and `update` skills for PACKAGE.md generation
+  - Plugin manifest auto-discovered by yoker
+- **Skills integration**: Skills moved into package for plugin distribution
+  - `create` skill: Generate PACKAGE.md for Python projects
+  - `update` skill: Update documentation for new versions
+- **Module restructuring**: Added `plugin.py` module for yoker integration
+  - Clean separation between core API and plugin interface
+  - Mirrors existing `mcp.py` architecture pattern
+
+### Breaking Changes
+
+- **Skills location**: Skills moved from `skills/` to `src/pkgq/skills/`
+  - Root `skills/` now a symlink for local development
+  - Skills distributed with package when installed as yoker plugin
+
+### Dependencies
+
+- Added `yoker>=0.5.0` as required dependency
+- Existing dependencies: httpx>=0.27.0, pydantic>=2.0.0, rich>=13.0.0
+
+---
+
+## 0.2.0 (2026-05-26)
+
+### New Features
+
+- Added plugin structure for Claude Code integration
+- Added CI/CD with GitHub Actions
+- Added PACKAGE.md for agent-ready documentation
+- Added `save` parameter to MCP tool with auto-cache results
+
+---
+
+## 0.1.1 (2026-05-26)
+
+## 0.1.1 (2026-05-26)
+
+### New Features
+- Added `save` parameter to MCP tool with auto-cache results
+- Cascade lookup: cache → GitHub → PyPI
+- CLI with `find` and `cache` commands
+- MCP server for Claude Code integration
+- Local caching at `~/.cache/pkgq/packages/`
+
+### Bug Fixes
+- Fixed license format and linter issues for PyPI compatibility
+
+---
+
+## 0.1.0 (2026-05-26)
+
+### New Features
+- Initial implementation of pkgq (package query)
+- `find()` function to query Python package information
+- `FindResult` dataclass for package information
+- GitHub PACKAGE.md fetching
+- PyPI documentation generation fallback

pkgq-0.3.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src/pkgq/skills *.md
+graft src/pkgq/skills

{pkgq-0.2.0 → pkgq-0.3.0}/PACKAGE.md

@@ -168,6 +168,27 @@ The MCP server provides the `find_package` tool for Claude Code and other MCP-co
 export PKGQ_CACHE=/path/to/cache
 ```
 
+## Yoker Plugin
+
+When using pkgq with the yoker agent harness, it can be loaded as a plugin to provide
+tools and skills directly within yoker sessions.
+
+```bash
+# Run yoker with pkgq plugin
+uvx --with pkgq yoker --with pkgq
+```
+
+This exposes:
+
+**Tools:**
+- `pkgq:find` - Find package documentation
+
+**Skills:**
+- `pkgq:create` - Generate PACKAGE.md for Python projects
+- `pkgq:update` - Update package documentation for new versions
+
+The plugin manifest is automatically discovered when pkgq is loaded as a yoker plugin.
+
 ## Dependencies
 
 | Package | Purpose |
@@ -175,14 +196,17 @@ export PKGQ_CACHE=/path/to/cache
 | `httpx>=0.27.0` | HTTP client for API requests |
 | `pydantic>=2.0.0` | Data validation (optional, for future use) |
 | `rich>=13.0.0` | Terminal output formatting |
+| `yoker>=0.5.0` | Yoker plugin system (required) |
 | `fastmcp>=3.0.0` | MCP server implementation (optional, `[mcp]` extra) |
 
 ## Version Notes
 
-**Current Version:** 0.1.1
+**Current Version:** 0.3.0
 
 ### Recent Features
 
+- Added yoker plugin support with tools and skills
+- Moved skills into package for plugin distribution
 - Added `save` parameter to MCP tool with auto-cache results
 - Fixed license format and linter issues for PyPI compatibility
 - Initial implementation with cascade lookup (cache → GitHub → PyPI)

{pkgq-0.2.0 → pkgq-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkgq
-Version: 0.2.0
+Version: 0.3.0
 Summary: Package Query - Find API information for Python packages
 Project-URL: Homepage, https://github.com/christophevg/pkgq
 Project-URL: Documentation, https://github.com/christophevg/pkgq#readme
@@ -22,6 +22,7 @@ Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
+Requires-Dist: yoker>=0.5.0
 Provides-Extra: dev
 Requires-Dist: build>=1.0.0; extra == 'dev'
 Requires-Dist: coveralls>=3.3.0; extra == 'dev'
@@ -47,6 +48,7 @@ Description-Content-Type: text/markdown
 [![License](https://img.shields.io/github/license/christophevg/pkgq.svg)][license]
 [![Agentic](https://img.shields.io/badge/workflow-agentic-blueviolet?style=flat-square)](https://christophe.vg/about/Agentic-Workflow)
 [![PACKAGE.md](https://img.shields.io/badge/pkgq-PACKAGE.md-blueviolet)](https://github.com/christophevg/pkgq#readme)
+[![yoker](https://img.shields.io/badge/yoker-plugin-blueviolet)](https://github.com/christophevg/yoker#readme)
   
 > Make your Python package discoverable for AI coding agents in 3 steps.
 
@@ -134,9 +136,64 @@ visibility into agent operations.
 
 % pkgq cache --list
 Cached packages (3):
-  pkgq 0.1.1 (pypi)
+  pkgq 0.3.0 (pypi)
   roomz 0.2.0 (github:christophevg/roomz)
-  yoker 0.4.0 (github:christophevg/yoker)
+  yoker 0.5.0 (github:christophevg/yoker)
+```
+
+### Yoker Tool
+
+When you're using yoker as your agent harness, you can simply include the pkgq package in your environment and ask yoker to load it as a plugin...
+
+```console
+% uvx --with pkgq yoker --with pkgq
+
+╭───────────────────────────────── Plugin: pkgq ──────────────────────────────────╮
+│ Plugin: pkgq                                                                    │
+│                                                                                 │
+│ Tools:     pkgq:find                                                            │
+│ Skills:    pkgq:create, pkgq:update                                             │
+│ Agents:    (none)                                                               │
+│                                                                                 │
+│ Plugins can execute code on your system.                                        │
+│ Only load plugins you trust.                                                    │
+│                                                                                 │
+│ Load this plugin? [y/N]:                                                        │
+╰─────────────────────────────────────────────────────────────────────────────────╯
+
+y
+
+To trust this plugin permanently, add to your yoker.toml:
+
+  [plugins.trusted]
+  pkgq = true
+
+╭───────────────────────────────── 👋 Welcome... ─────────────────────────────────╮
+│ Yoker v0.4.0 - Using model: kimi-k2.7-code:cloud                                │
+│ Harness: yoker v1.0                                                             │
+│ Thinking mode: enabled (use /think on|off|silent to toggle)                     │
+│ Agent: default - The default/minimal Yoker agent.                               │
+│ Type /help for available commands.                                              │
+│ Press Ctrl+D (or Ctrl+Z on Windows) to quit.                                    │
+╰─────────────────────────────────────────────────────────────────────────────────╯
+
+> use the pkgq find tool to get information on pkgq
+  The user wants me to use the pkgq find tool to get information on pkgq. I should
+  use the pkgq__find function with package="pkgq".
+
+⏺ Pkgq:find tool: pkgq  ✓ Success
+  I got the information from the pkgq find tool. Let me summarize this for the user
+  in a helpful way.
+
+  Here is the information for **pkgq** using the pkgq find tool:
+
+  ## pkgq — Package Query
+
+  - **Version:** 0.1.1
+  - **Author:** None listed
+  - **Description:** Package Query - Find API information for Python packages
+  - **Install command:**
+    pip install pkgq
 ```
 
 ### MCP Server
@@ -146,6 +203,75 @@ pkgq-mcp-server
 # Or: uvx --from "pkgq[mcp]" pkgq-mcp-server
 ```
 
+So If you want to load it into your project, create a `.mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "pkgq": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "pkgq[mcp]",
+        "pkgq-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+When you start your MCP-based coding harness, e.g. Claude Code, you'll be prompted for confirmation to use the new MCP server:
+
+```
+────────────────────────────────────────────────────────────────────────────────────
+  New MCP server found in this project: pkgq
+
+  MCP servers may execute code or access system resources. All tool calls require
+  approval. Learn more in the MCP documentation.
+
+  ❯ 1. Use this MCP server
+    2. Use this and all future MCP servers in this project
+    3. Continue without using this MCP server
+
+  Enter to confirm · Esc to cancel
+  ```
+
+And you can use it:
+
+```
+❯ use the find_pacakge tool to find information about pkgq
+
+⏺ Thinking for 2s, calling plugin:c3:pkgq…
+
+────────────────────────────────────────────────────────────────────────────────────
+ Tool use
+
+   plugin:c3:pkgq - find_package(package: "pkgq") (MCP)
+   Find package documentation.
+
+   Queries multiple sources in order:…
+
+ Do you want to proceed?
+ ❯ 1. Yes
+   2. Yes, and don't ask again for plugin:c3:pkgq - find_package commands in /Users/xtof/Workspace/agentic/pkgq
+   3. No
+
+ Esc to cancel · Tab to amend
+
+
+ pkgq Package Information
+ 
+ Version: 0.1.1 (cached)
+ Source: PyPI
+ 
+ Overview
+ 
+ pkgq (Package Query) is a tool for finding API information for Python packages.
+ ...
+```
+
+
+
 ## Features
 
 | Feature | Description |
@@ -173,3 +299,4 @@ pkgq-mcp-server
 [ci]: https://github.com/christophevg/pkgq/actions
 [coveralls]: https://coveralls.io/github/christophevg/pkgq
 [license]: https://github.com/christophevg/pkgq/blob/main/LICENSE
+

pkgq-0.3.0/README.md

@@ -0,0 +1,262 @@
+# pkgq
+
+[![PyPI](https://img.shields.io/pypi/v/pkgq.svg)][pypi]
+[![Python](https://img.shields.io/pypi/pyversions/pkgq.svg)][pypi]
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)][uv]
+[![CI](https://img.shields.io/github/actions/workflow/status/christophevg/pkgq/test.yml.svg)][ci]
+[![Coverage](https://img.shields.io/coveralls/github/christophevg/pkgq.svg)][coveralls]
+[![License](https://img.shields.io/github/license/christophevg/pkgq.svg)][license]
+[![Agentic](https://img.shields.io/badge/workflow-agentic-blueviolet?style=flat-square)](https://christophe.vg/about/Agentic-Workflow)
+[![PACKAGE.md](https://img.shields.io/badge/pkgq-PACKAGE.md-blueviolet)](https://github.com/christophevg/pkgq#readme)
+[![yoker](https://img.shields.io/badge/yoker-plugin-blueviolet)](https://github.com/christophevg/yoker#readme)
+  
+> Make your Python package discoverable for AI coding agents in 3 steps.
+
+## What is PACKAGE.md?
+
+**PACKAGE.md** is a informally proposed documentation standard for Python packages optimized for AI agents. Unlike README.md (written for humans), PACKAGE.md provides structured, scannable content that coding agents can quickly understand:
+
+- **Purpose** - What the package does in one line
+- **Key Components** - Classes, functions, and their signatures
+- **Common Patterns** - Code examples for typical use cases
+- **Migration Guides** - How to upgrade between versions
+
+When you add PACKAGE.md to your repository root, coding agents using `pkgq` can instantly understand your package's capabilities.
+
+## Quick Start for Package Authors
+
+**3 steps to make your package discoverable:**
+
+```bash
+# 0. Add the marketplace (one-time setup)
+claude plugin marketplace add christophevg/marketplace
+
+# 1. Get the plugin
+claude plugin install pkgq@christophe.vg
+
+# 2. Generate documentation
+/pkgq:create
+
+# 3. Commit and push
+git add PACKAGE.md && git commit -m "docs: add PACKAGE.md" && git push
+```
+
+Done! Your package is now discoverable by coding agents using the `pkgq` tool or MCP server.
+
+**Add the badge to show your package supports AI agents:**
+
+```markdown
+[![PACKAGE.md](https://img.shields.io/badge/pkgq-PACKAGE.md-blueviolet)](https://github.com/christophevg/pkgq#readme)
+```
+
+## For Package Users
+
+### Installation
+
+```bash
+pip install pkgq
+
+# For MCP server support
+pip install "pkgq[mcp]"
+```
+
+### Python Module
+
+```python
+from pkgq import find
+
+# Find package documentation
+result = find("yoker")
+print(result.content)
+
+# Check for updates
+result = find("yoker", from_version="1.5.0")
+```
+
+### Command Line
+
+```bash
+% pkgq find yoker --save | head -15
+Saved to: /Users/xtof/.cache/pkgq/packages/yoker
+yoker 0.4.0 (cached)
+Source: github:christophevg/yoker
+
+                              Yoker
+
+A Python agent harness with configurable tools and guardrails - one who yokes
+agents together.
+
+Overview
+
+Yoker is a library-first, event-driven agent harness for Python that integrates
+with Ollama. It provides a transparent, configurable runtime for AI agents with
+structured tool execution, guardrails, and event emission. Unlike CLI-first
+agent frameworks, Yoker is designed to be embedded in applications with full
+visibility into agent operations.
+
+% pkgq cache --list
+Cached packages (3):
+  pkgq 0.3.0 (pypi)
+  roomz 0.2.0 (github:christophevg/roomz)
+  yoker 0.5.0 (github:christophevg/yoker)
+```
+
+### Yoker Tool
+
+When you're using yoker as your agent harness, you can simply include the pkgq package in your environment and ask yoker to load it as a plugin...
+
+```console
+% uvx --with pkgq yoker --with pkgq
+
+╭───────────────────────────────── Plugin: pkgq ──────────────────────────────────╮
+│ Plugin: pkgq                                                                    │
+│                                                                                 │
+│ Tools:     pkgq:find                                                            │
+│ Skills:    pkgq:create, pkgq:update                                             │
+│ Agents:    (none)                                                               │
+│                                                                                 │
+│ Plugins can execute code on your system.                                        │
+│ Only load plugins you trust.                                                    │
+│                                                                                 │
+│ Load this plugin? [y/N]:                                                        │
+╰─────────────────────────────────────────────────────────────────────────────────╯
+
+y
+
+To trust this plugin permanently, add to your yoker.toml:
+
+  [plugins.trusted]
+  pkgq = true
+
+╭───────────────────────────────── 👋 Welcome... ─────────────────────────────────╮
+│ Yoker v0.4.0 - Using model: kimi-k2.7-code:cloud                                │
+│ Harness: yoker v1.0                                                             │
+│ Thinking mode: enabled (use /think on|off|silent to toggle)                     │
+│ Agent: default - The default/minimal Yoker agent.                               │
+│ Type /help for available commands.                                              │
+│ Press Ctrl+D (or Ctrl+Z on Windows) to quit.                                    │
+╰─────────────────────────────────────────────────────────────────────────────────╯
+
+> use the pkgq find tool to get information on pkgq
+  The user wants me to use the pkgq find tool to get information on pkgq. I should
+  use the pkgq__find function with package="pkgq".
+
+⏺ Pkgq:find tool: pkgq  ✓ Success
+  I got the information from the pkgq find tool. Let me summarize this for the user
+  in a helpful way.
+
+  Here is the information for **pkgq** using the pkgq find tool:
+
+  ## pkgq — Package Query
+
+  - **Version:** 0.1.1
+  - **Author:** None listed
+  - **Description:** Package Query - Find API information for Python packages
+  - **Install command:**
+    pip install pkgq
+```
+
+### MCP Server
+
+```bash
+pkgq-mcp-server
+# Or: uvx --from "pkgq[mcp]" pkgq-mcp-server
+```
+
+So If you want to load it into your project, create a `.mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "pkgq": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "pkgq[mcp]",
+        "pkgq-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+When you start your MCP-based coding harness, e.g. Claude Code, you'll be prompted for confirmation to use the new MCP server:
+
+```
+────────────────────────────────────────────────────────────────────────────────────
+  New MCP server found in this project: pkgq
+
+  MCP servers may execute code or access system resources. All tool calls require
+  approval. Learn more in the MCP documentation.
+
+  ❯ 1. Use this MCP server
+    2. Use this and all future MCP servers in this project
+    3. Continue without using this MCP server
+
+  Enter to confirm · Esc to cancel
+  ```
+
+And you can use it:
+
+```
+❯ use the find_pacakge tool to find information about pkgq
+
+⏺ Thinking for 2s, calling plugin:c3:pkgq…
+
+────────────────────────────────────────────────────────────────────────────────────
+ Tool use
+
+   plugin:c3:pkgq - find_package(package: "pkgq") (MCP)
+   Find package documentation.
+
+   Queries multiple sources in order:…
+
+ Do you want to proceed?
+ ❯ 1. Yes
+   2. Yes, and don't ask again for plugin:c3:pkgq - find_package commands in /Users/xtof/Workspace/agentic/pkgq
+   3. No
+
+ Esc to cancel · Tab to amend
+
+
+ pkgq Package Information
+ 
+ Version: 0.1.1 (cached)
+ Source: PyPI
+ 
+ Overview
+ 
+ pkgq (Package Query) is a tool for finding API information for Python packages.
+ ...
+```
+
+
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Cascade lookup | Cache → GitHub PACKAGE.md → PyPI |
+| MCP server | Tool for Claude Code agents |
+| Auto-caching | Results saved to `~/.cache/pkgq/packages/` |
+| Plugin skills | `/pkgq:create` and `/pkgq:update` |
+
+## Development
+
+```bash
+% git clone https://github.com/christophevg/pkgq.git
+% cd pkgq
+% uv sync --all-extras
+% uv run pytest
+```
+
+## License
+
+[MIT](LICENSE)
+
+[pypi]: https://pypi.org/project/pkgq/
+[uv]: https://docs.astral.sh/uv/
+[ci]: https://github.com/christophevg/pkgq/actions
+[coveralls]: https://coveralls.io/github/christophevg/pkgq
+[license]: https://github.com/christophevg/pkgq/blob/main/LICENSE
+