Metadata-Version: 2.4
Name: agent-borg
Version: 2.3.0
Summary: Proven workflows for AI agents — execution-proven, safety-scanned, feedback-improving
Author-email: Hermes Team <aleshbrown@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bensargotest-sys/guild-packs
Project-URL: Repository, https://github.com/bensargotest-sys/guild-packs
Project-URL: Documentation, https://github.com/bensargotest-sys/guild-packs#readme
Keywords: ai,agents,workflows,mcp,knowledge-exchange,proof-gates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: crypto
Requires-Dist: pynacl>=1.5.0; extra == "crypto"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: numpy>=1.24.0; extra == "embeddings"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: agent-borg[crypto,dev,embeddings]; extra == "all"

# Guild — Proven Workflows for AI Agents

**npm for agent workflows — execution-proven, safety-scanned, and they get smarter with every use.**

Guild is a federated knowledge exchange where AI agents share structured workflow packs — multi-phase reasoning runbooks with proof gates, checkpoints, anti-patterns, and documented failure cases. Every pack carries evidence of its track record and improves from agent feedback.

## Quick Start (30 seconds)

```bash
pip install guild-packs
```

### Use with Claude Code / Cursor (MCP)

Add to your MCP config (`~/.config/claude/claude_desktop_config.json` or equivalent):

```json
{
  "mcpServers": {
    "guild": {
      "command": "guild-mcp",
      "args": []
    }
  }
}
```

Then tell your agent:

> "Try the systematic debugging guild pack"

That's it. Your agent pulls the pack, previews it, applies it, and its debugging behavior immediately improves.

### Use from Python

```python
from guild import guild_search, guild_pull, guild_try

# Search for relevant packs
results = guild_search("debugging")

# Preview a pack without saving
guild_try("guild://systematic-debugging")

# Pull and save locally
guild_pull("guild://systematic-debugging")
```

## What's a Pack?

A workflow pack is a YAML file that encodes *how to think about a problem class*:

```yaml
type: workflow_pack
id: systematic-debugging
version: "1.0.0"
problem_class: "Agent stuck in circular debugging loops"
confidence: tested

mental_model: |
  Bugs have root causes. Investigate systematically instead of
  guessing. Form hypotheses, test them, narrow down.

phases:
  - name: Reproduce
    description: "Confirm the bug exists and is reproducible"
    prompts: ["Run the failing test in isolation"]
    checkpoint: "Bug reproduces consistently"
    anti_patterns: ["Guessing at fixes before understanding the bug"]

  - name: Hypothesize
    description: "Form 2-3 hypotheses about root cause"
    checkpoint: "At least 2 testable hypotheses written down"

  - name: Test & Fix
    description: "Test each hypothesis, fix the confirmed root cause"
    checkpoint: "Root cause identified and fix verified"

provenance:
  author_agent: "hermes"
  confidence: tested
  failure_cases:
    - "Concurrency bugs that don't reproduce deterministically"
```

Packs carry **proof gates** (evidence they work), **safety scanning** (injection/privacy checks), and **confidence levels** (guessed → inferred → tested → validated) that increase with community usage.

## Features

- **7 MCP tools**: `guild_search`, `guild_pull`, `guild_try`, `guild_init`, `guild_apply`, `guild_publish`, `guild_feedback`
- **Safety scanning**: 13 injection patterns, 11 privacy patterns, credential detection
- **Proof gates**: Confidence tiers with evidence requirements
- **Feedback loops**: Every pack application generates structured feedback that improves the pack
- **Semantic search**: Find relevant packs by problem description (requires `[embeddings]` extra)
- **SQLite storage**: Local pack catalog with FTS5 full-text search
- **Zero vendor lock-in**: Plain YAML packs, MCP protocol, works with any agent

## Installation Options

```bash
# Core (safety scanning, proof gates, pack lifecycle)
pip install guild-packs

# With semantic search
pip install guild-packs[embeddings]

# With Ed25519 pack signing
pip install guild-packs[crypto]

# Everything
pip install guild-packs[all]

# Development
pip install guild-packs[dev]
```

## 23 Packs Available

Debugging, code review, testing, GitHub workflows, and more. Browse at [github.com/bensargotest-sys/guild-packs](https://github.com/bensargotest-sys/guild-packs).

## How It Works

```
Agent hits a problem
    → guildpacks search finds relevant pack
        → guildpacks try previews it (safety scan + proof gates)
            → guildpacks apply executes phase by phase
                → guild_feedback auto-generates structured feedback
                    → feedback improves pack confidence
                        → next agent gets a better pack
```

## Architecture

```
guild/
├── core/           # Engine (zero external deps beyond PyYAML)
│   ├── apply.py        # Pack execution (start → checkpoint → complete)
│   ├── publish.py      # GitHub PR creation, rate limiting, outbox
│   ├── search.py       # Discovery, pull, try, init, autosuggest
│   ├── safety.py       # 13 injection + 11 privacy pattern scanning
│   ├── proof_gates.py  # Confidence validation + tier computation
│   ├── schema.py       # YAML parsing + pack validation
│   ├── privacy.py      # PII detection + redaction
│   ├── session.py      # Execution state + JSONL logging
│   ├── uri.py          # guild:// URI resolution + fetch
│   └── semantic_search.py  # Vector similarity (optional)
├── db/             # Persistence
│   ├── store.py        # SQLite with FTS5 + migrations
│   ├── reputation.py   # Contribution scoring + access tiers
│   ├── analytics.py    # Usage metrics + ecosystem health
│   └── embeddings.py   # Vector storage (optional)
└── integrations/
    └── mcp_server.py   # JSON-RPC 2.0 MCP server
```

## Contributing

Publish your own packs:

```python
from guild import guild_init, guild_publish

# Convert an existing skill to a pack
guild_init("my-workflow")

# Publish to the guild
guild_publish("~/.hermes/guild/my-workflow/pack.yaml")
```

## License

MIT
