agentweld 0.1.0__tar.gz

agentweld-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# agentforge output (generated artifacts — not source code)
+agent/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp

agentweld-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to agentweld are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/).
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-03-22
+
+Initial public release of agentweld.
+
+### Added
+
+**Phase 1 — Core models and utilities**
+- `ToolDefinition` Pydantic model — universal data model for all pipeline stages. `description_original` is immutable; all curation writes to `description_curated`.
+- `QualityFlag` enum — 7 quality flags: `MISSING_DESCRIPTION`, `WEAK_DESCRIPTION`, `POOR_NAMING`, `UNDOCUMENTED_PARAMS`, `NO_ERROR_GUIDANCE`, `DUPLICATE_INTENT`, `OVERLOADED_TOOL`.
+- `AgentForgeConfig` Pydantic model tree — full `agentweld.yaml` schema.
+- `AgentForgeError` exception hierarchy — 8 typed error classes.
+- Rich console singleton, table builders, and score formatting utilities.
+
+**Phase 2 — Source adapters**
+- `MCPStdioAdapter` — spawns a subprocess, calls `tools/list`, terminates. Security: `--trust` flag required for all stdio sources.
+- `MCPHttpAdapter` — streamable-HTTP MCP transport.
+- Adapter registry with plugin discovery via `agentweld.adapters` entry-point group.
+
+**Phase 3 — Configuration I/O**
+- `config/loader.py` — parse, env-interpolate, and validate `agentweld.yaml`.
+- `config/writer.py` — `ruamel.yaml` round-trip with comment preservation.
+
+**Phase 4 — Curation engine**
+- `QualityScanner` — 7-flag rubric producing 0.0–1.0 quality scores per tool.
+- `RuleBasedCurator` — filter (include/exclude lists), rename, description override.
+- `CurationEngine` — orchestrates scanner → rule curator. LLM enrichment is never triggered here.
+
+**Phase 5 — Artifact generators**
+- `AgentCardGenerator` — A2A-valid `agent_card.json`.
+- `ToolManifestGenerator` — `mcp.json` tool manifest.
+- `SystemPromptGenerator` — `system_prompt.md` via Jinja2.
+- `ReadmeGenerator` — `README.md` via Jinja2.
+
+**Phase 6 — CLI**
+- `agentweld init` — scaffold `agentweld.yaml` from an MCP source.
+- `agentweld add` — append an MCP source to an existing project.
+- `agentweld inspect` — view tool quality metrics (`--source`, `--final`, `--conflicts`).
+- `agentweld generate` — run the full pipeline (`--force`, `--only`, `--output-dir`).
+- `agentweld preview` — dry-run generation with artifact output.
+
+**Phase 7 — Integration and polish**
+- 172 tests, ~88% coverage.
+- Multi-source concurrent introspection via `anyio.create_task_group()`.
+- Quality gate in the `generate` pipeline (configurable `quality.block_below` threshold).
+- Conflict resolution strategies: `prefix`, `explicit`, `error`.
+
+[0.1.0]: https://github.com/sheshnath08/agentweld/releases/tag/v0.1.0

agentweld-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to agentweld
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/sheshnath08/agentweld
+cd agentweld
+
+# Using uv (recommended)
+uv venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Or with standard venv
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+See [CLAUDE.md](CLAUDE.md) for the full list of development commands (tests, lint, type checking, individual test runs).
+
+## Code Quality
+
+Run all of the following before submitting a PR:
+
+```bash
+ruff check src/          # lint
+ruff format src/         # format
+mypy src/agentweld      # type checking
+pytest tests/unit/       # unit tests (no live MCP connections required)
+```
+
+All four must pass. CI enforces the same checks.
+
+## Pull Request Process
+
+1. Fork the repo and create a branch from `main`.
+2. Add tests for any new behaviour. Unit tests live in `tests/unit/`, integration tests in `tests/integration/`.
+3. Ensure `ruff`, `mypy`, and `pytest tests/unit/` all pass locally.
+4. Open a PR against `main`. Describe **what** changed and **why**.
+
+## Architecture Overview
+
+See [CLAUDE.md](CLAUDE.md) for the full module layout and pipeline stages.
+
+**The most important invariant:** `ToolDefinition.description_original` is set once on construction and must never be modified. All curation writes exclusively to `description_curated`. Breaking this invariant corrupts the provenance chain and will be rejected.
+
+Other key decisions:
+- `SourceAdapter` is a `typing.Protocol` — third-party adapters do not need to import agentweld internals.
+- LLM enrichment is **explicit-only** — it never runs silently during `generate`. Only via an explicit `agentweld enrich` call.
+- `--trust` is required for stdio sources — spawning arbitrary subprocesses is code execution; opt-in is non-negotiable.
+- `ruamel.yaml` is used over PyYAML to preserve YAML comments on round-trip.
+
+## Writing a Source Adapter Plugin
+
+A source adapter is any class that satisfies the `SourceAdapter` Protocol. No inheritance from agentweld is required.
+
+**Required interface** (from `src/agentweld/sources/base.py`):
+
+```python
+class MyAdapter:
+    async def introspect(self, config: SourceConfig) -> list[ToolDefinition]:
+        """Connect to the source and return normalized ToolDefinition objects.
+
+        Raises:
+            SourceConnectionError: if the source cannot be reached.
+        """
+        ...
+
+    async def health_check(self, config: SourceConfig) -> bool:
+        """Return True if reachable; False otherwise. Must not raise."""
+        ...
+```
+
+**Register via entry point** in your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."agentweld.adapters"]
+my-transport = "my_package.adapter:MyAdapter"
+```
+
+The key (`my-transport`) becomes the `--from` value users pass to `init` and `add`.
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+| Prefix | When to use |
+|--------|-------------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `docs:` | Documentation only |
+| `test:` | Test additions or fixes |
+| `refactor:` | Code change with no feature/bug impact |
+| `chore:` | Tooling, CI, or dependency changes |

agentweld-0.1.0/LICENSE

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

agentweld-0.1.0/PKG-INFO

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: agentweld
+Version: 0.1.0
+Summary: Turn any MCP server into a curated, composable, A2A-ready agent.
+Project-URL: Homepage, https://github.com/sheshnath08/agentweld
+Project-URL: Repository, https://github.com/sheshnath08/agentweld
+Project-URL: Bug Tracker, https://github.com/sheshnath08/agentweld/issues
+Project-URL: Changelog, https://github.com/sheshnath08/agentweld/blob/main/CHANGELOG.md
+Author-email: Sheshnath Yadav <sheshnathyadav08@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026: Sheshnath Yadav
+        
+        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.
+License-File: LICENSE
+Keywords: a2a,agent,agentic,llm,mcp,model-context-protocol,tool-curation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer[all]>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentweld
+
+> Turn any MCP server into a curated, composable, A2A-ready agent.
+
+[![PyPI version](https://img.shields.io/pypi/v/agentweld)](https://pypi.org/project/agentweld/)
+[![Python 3.11+](https://img.shields.io/pypi/pyversions/agentweld)](https://pypi.org/project/agentweld/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/sheshnath08/agentweld/actions/workflows/ci.yml/badge.svg)](https://github.com/sheshnath08/agentweld/actions/workflows/ci.yml)
+
+## What is agentweld?
+
+The MCP ecosystem has servers — lots of them. What it's missing is a way to turn those servers into purposeful, well-described, discoverable agents. Raw MCP servers expose dozens or hundreds of tools with weak descriptions, inconsistent naming, and no quality signal. Clients have no way to know which tools are useful, what they do, or how to combine them.
+
+**agentweld** solves both problems. It connects to one or more MCP servers, runs a quality scan across every exposed tool, lets you curate the results (filter, rename, enrich descriptions), then generates a complete set of deployment artifacts: an A2A-valid agent card, a tool manifest, a system prompt, and a README — all from a single `agentweld.yaml`.
+
+## The Pipeline
+
+```
+SOURCE LAYER  (MCP servers → tools/list)
+  ↓  ToolDefinition[]
+CURATION ENGINE  (quality scanner → rule-based curator → LLM enrichment)
+  ↓
+COMPOSITION LAYER  (namespace merge, conflict resolution)
+  ↓
+GENERATORS  →  agent_card.json  /  mcp.json  /  system_prompt.md  /  README.md
+```
+
+## Quick Start
+
+### Install
+
+```bash
+pip install agentweld
+```
+
+### 5-command walkthrough
+
+```bash
+# 1. Scaffold a project from an MCP server
+#    --trust is required for stdio sources (spawning npx is code execution)
+$ agentweld init "npx @modelcontextprotocol/server-github" --trust
+WARNING: --trust flag set. Spawning subprocess: npx @modelcontextprotocol/server-github
+Connecting to npx @modelcontextprotocol/server-github...
+Discovered 26 tools.
+Created ./agentweld.yaml
+
+# 2. (Optional) Add a second source
+$ agentweld add "npx @linear/mcp" --trust
+
+# 3. Check tool quality before generating
+$ agentweld inspect
+┌──────────┬───────┬─────────────┐
+│ Source   │ Tools │ Avg Quality │
+├──────────┼───────┼─────────────┤
+│ github   │  26   │   0.54 ⚠    │
+│ linear   │  24   │   0.71      │
+└──────────┴───────┴─────────────┘
+
+# 4. Edit agentweld.yaml to filter, rename, or override descriptions
+#    (see Configuration Reference below)
+
+# 5. Generate artifacts
+$ agentweld generate
+Generated 4 artifact(s) in ./agent:
+  • agent_card.json
+  • mcp.json
+  • system_prompt.md
+  • README.md
+```
+
+## CLI Reference
+
+### `agentweld init`
+
+Scaffold a new `agentweld.yaml` from an MCP source.
+
+```
+agentweld init SOURCE [OPTIONS]
+
+Arguments:
+  SOURCE    MCP server command (stdio) or URL (http/https)
+
+Options:
+  --from TEXT         Source type [default: mcp]
+  --trust             Trust and execute the stdio command (required for npx/docker)
+  -o, --output PATH   Output directory [default: .]
+  -n, --name TEXT     Agent name
+```
+
+> **Security:** `--trust` is required for any stdio source because spawning `npx`, `docker`, or any arbitrary command is code execution. HTTP/HTTPS sources do not require it.
+
+### `agentweld add`
+
+Add another MCP source to an existing project.
+
+```
+agentweld add SOURCE [OPTIONS]
+
+Arguments:
+  SOURCE    MCP server command (stdio) or URL (http/https)
+
+Options:
+  --from TEXT         Source type [default: mcp]
+  --trust             Trust and execute the stdio command
+  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
+```
+
+### `agentweld inspect`
+
+Inspect tools and quality metrics for all configured sources.
+
+```
+agentweld inspect [OPTIONS]
+
+Options:
+  --source            Show raw tools per source (pre-curation)
+  --final             Show post-curation tools
+  --conflicts         Show naming conflicts across sources
+  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
+```
+
+### `agentweld generate`
+
+Run the full pipeline and write artifacts to the output directory.
+
+```
+agentweld generate [OPTIONS]
+
+Options:
+  --force             Overwrite existing artifacts and bypass the quality gate
+  --only TEXT         Only generate specific artifacts (repeatable):
+                      agent_card | tool_manifest | system_prompt | readme
+  -o, --output-dir PATH   Override the output directory from agentweld.yaml
+  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
+```
+
+### `agentweld preview`
+
+Same as `generate` but writes to a temp directory and prints artifact contents. Nothing is written to your project.
+
+```
+agentweld preview [OPTIONS]
+
+Options:
+  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
+```
+
+## Configuration Reference
+
+`agentweld.yaml` is the single source of truth for the entire pipeline. Here is an annotated example:
+
+```yaml
+meta:
+  created_at: "2026-01-01T00:00:00+00:00"
+  updated_at: "2026-01-01T00:00:00+00:00"
+
+agent:
+  name: "My Dev Agent"
+  description: "An agent for GitHub and Linear workflows."
+  version: "0.1.0"
+
+sources:
+  - id: github
+    type: mcp_server
+    transport: stdio
+    command: "npx @modelcontextprotocol/server-github"
+    # env:
+    #   GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
+
+  - id: linear
+    type: mcp_server
+    transport: streamable-http
+    url: "https://mcp.linear.app/sse"
+
+tools:
+  filters:
+    github:
+      # include and exclude are mutually exclusive — use one or the other
+      include:
+        - search_repositories
+        - create_issue
+        - list_pull_requests
+      # exclude:
+      #   - delete_repository
+
+  rename:
+    "github::search_repositories": search_repos
+    "linear::create_issue": linear_create_issue
+
+  descriptions:
+    # Written here by `agentweld enrich` — safe to edit manually too
+    search_repos: "Search GitHub repositories by keyword, language, or topic."
+
+quality:
+  block_below: 0.4    # Quality gate: fail generate if avg score < this threshold
+                      # Use --force to bypass
+
+composition:
+  conflict_strategy: prefix   # prefix | explicit | error
+                              # prefix: prepend source_id:: to conflicting names
+                              # explicit: require rename in tools.rename
+                              # error: abort on any conflict
+
+a2a:
+  skills:
+    - id: code-search
+      name: "Code Search"
+      description: "Search repositories and navigate codebases."
+      tags: [github, search]
+
+generate:
+  output_dir: ./agent
+  emit:
+    agent_card: true
+    tool_manifest: true
+    system_prompt: true
+    readme: true
+```
+
+## Generated Artifacts
+
+| Artifact | Path | Purpose |
+|---|---|---|
+| `agent_card.json` | `<output_dir>/agent_card.json` | A2A Agent Card, suitable for hosting at `/.well-known/agent.json` |
+| `mcp.json` | `<output_dir>/mcp.json` | Tool manifest for MCP clients |
+| `system_prompt.md` | `<output_dir>/system_prompt.md` | LLM system prompt describing the agent and its tools |
+| `README.md` | `<output_dir>/README.md` | Quickstart for users of the generated agent |
+
+## Plugin System
+
+agentweld discovers third-party source adapters via the `agentweld.adapters` entry-point group. No inheritance from agentweld internals is required — structural subtyping (Protocol) is used.
+
+**Implement the `SourceAdapter` protocol:**
+
+```python
+# my_package/adapter.py
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentweld.models.config import SourceConfig
+    from agentweld.models.tool import ToolDefinition
+
+
+class MyAdapter:
+    async def introspect(self, config: SourceConfig) -> list[ToolDefinition]:
+        """Connect to the source and return normalized ToolDefinition objects."""
+        ...
+
+    async def health_check(self, config: SourceConfig) -> bool:
+        """Return True if the source is reachable; False otherwise. Must not raise."""
+        ...
+```
+
+**Register it in your package's `pyproject.toml`:**
+
+```toml
+[project.entry-points."agentweld.adapters"]
+my-transport = "my_package.adapter:MyAdapter"
+```
+
+After `pip install my-package`, agentweld discovers your adapter automatically. Use the transport key (`my-transport`) as the `--from` argument when running `init` or `add`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code quality requirements, and the PR process.
+
+## License
+
+MIT — see [LICENSE](LICENSE).