agentcard-disco 0.1.0__tar.gz

agentcard_disco-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[deep]"
+          pip install pytest pytest-cov
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=src/agentcard_disco --cov-report=term-missing
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff
+        run: ruff check src/
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[deep]"
+          pip install mypy
+
+      - name: Run mypy
+        run: mypy src/

agentcard_disco-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"   # triggers on: git tag v0.1.0 && git push --tags
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatch
+
+      - name: Build wheel and sdist
+        run: hatch build
+
+      - name: Upload dist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentcard_disco-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Reports (generated output)
+report.json
+report.md

agentcard_disco-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: agentcard-disco
+Version: 0.1.0
+Summary: Score and optimize A2A Agent Cards for discoverability
+Project-URL: Homepage, https://github.com/chinemeze/agentcard-disco
+Project-URL: Issues, https://github.com/chinemeze/agentcard-disco/issues
+Author: Chinemeze
+License: MIT
+Keywords: a2a,agent,agent-card,discoverability,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: deep
+Requires-Dist: google-genai>=1.0; extra == 'deep'
+Description-Content-Type: text/markdown
+
+# agentcard-disco
+
+**Score and optimise [A2A](https://agent2agent.info/) Agent Cards for discoverability.**
+
+`agentcard-disco` analyses an Agent Card JSON file and gives it a discoverability score across four heuristic dimensions (plus optional AI-assisted analysis), surfacing exactly what to fix before publishing to an A2A registry.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  agentcard-disco          discoverability score             │
+│                                                             │
+│  🏆  DataPulse Analytics Agent                              │
+│    Source: tests/fixtures/good_card.json                    │
+│                                                             │
+│    Score: 88.0 / 100   (88%)   Grade:  A                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+pip install agentcard-disco
+```
+
+For AI-assisted scoring (`--deep`):
+
+```bash
+pip install "agentcard-disco[deep]"
+```
+
+---
+
+## Quick start
+
+```bash
+# Score a local card
+agentcard-disco score ./agent-card.json
+
+# Score from a URL
+agentcard-disco score https://api.example.com/.well-known/agent-card.json
+
+# + AI quality analysis (requires GEMINI_API_KEY in .env)
+agentcard-disco score ./agent-card.json --deep
+
+# Export report as JSON or Markdown
+agentcard-disco score ./agent-card.json --format json --output report.json
+agentcard-disco score ./agent-card.json --format markdown --output report.md
+
+# CI gate — exit 1 if score is below 70%
+agentcard-disco score ./agent-card.json --fail-under 70
+
+# Get improvement suggestions only
+agentcard-disco suggest ./agent-card.json --priority high
+
+# Compare two cards side-by-side
+agentcard-disco compare ./v1.json ./v2.json
+```
+
+---
+
+## Scoring dimensions
+
+| Dimension | Points | What it measures |
+|-----------|-------:|-----------------|
+| Metadata Richness | 0–30 | Description length, tags, examples, provider info |
+| Semantic Specificity | 0–30 | Filler-word ratio, skill distinctness, action-verb density |
+| Search Alignment | 0–20 | Tag and keyword coverage vs A2A registry query vocabulary |
+| Completeness | 0–20 | SemVer, capabilities, auth declaration, protocol version |
+| AI Quality *(--deep)* | 0–20 | Categorical quality judgments via Gemini |
+
+**Grade scale:**
+
+| Grade | Score |
+|-------|-------|
+| A | 85–100% |
+| B | 70–84% |
+| C | 50–69% |
+| D | 30–49% |
+| F | 0–29% |
+
+---
+
+## AI scoring setup (`--deep`)
+
+1. Install the deep extra: `pip install "agentcard-disco[deep]"`
+2. Get a free Gemini API key at https://aistudio.google.com/app/apikey
+3. Add it to a `.env` file in your working directory:
+
+```env
+GEMINI_API_KEY="AIza..."
+```
+
+4. Run with `--deep`:
+
+```bash
+agentcard-disco score ./agent-card.json --deep
+```
+
+---
+
+## Python API
+
+```python
+from agentcard_disco.parser import load
+from agentcard_disco.scoring.engine import score
+
+card = load("agent-card.json")        # also accepts http(s):// URLs
+report = score(card)                  # Tier 1 only
+report = score(card, deep=True)       # + AI analysis
+
+print(report.grade.value)            # "A", "B", ...
+print(report.percentage)             # 88.0
+print(report.total_score)            # 88.0
+
+for suggestion in report.all_suggestions:
+    print(suggestion.priority, suggestion.field, suggestion.message)
+```
+
+---
+
+## Commands
+
+### `score`
+
+```
+agentcard-disco score SOURCE [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--deep` | off | Enable Tier 2 AI analysis (+20 pts) |
+| `--format` | terminal | `terminal`, `json`, or `markdown` |
+| `--output FILE` | stdout | Write output to file |
+| `--fail-under SCORE` | — | Exit 1 if percentage < SCORE |
+| `--no-suggestions` | off | Hide suggestions table |
+| `--no-detail` | off | Hide per-dimension details |
+
+### `suggest`
+
+```
+agentcard-disco suggest SOURCE [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--priority` | all | Filter: `all`, `high`, `medium`, `low` |
+| `--format` | terminal | `terminal` or `json` |
+| `--limit N` | 20 | Max suggestions to show |
+| `--deep` | off | Include AI suggestions |
+
+### `compare`
+
+```
+agentcard-disco compare SOURCE SOURCE [SOURCE ...] [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--format` | terminal | `terminal` or `json` |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/chinemeze/agentcard-disco
+cd agentcard-disco
+pip install -e ".[deep]"
+pip install pytest pytest-cov mypy ruff
+
+# Run tests
+pytest tests/ -v
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/
+```
+
+---
+
+## License
+
+MIT

agentcard_disco-0.1.0/README.md

@@ -0,0 +1,186 @@
+# agentcard-disco
+
+**Score and optimise [A2A](https://agent2agent.info/) Agent Cards for discoverability.**
+
+`agentcard-disco` analyses an Agent Card JSON file and gives it a discoverability score across four heuristic dimensions (plus optional AI-assisted analysis), surfacing exactly what to fix before publishing to an A2A registry.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  agentcard-disco          discoverability score             │
+│                                                             │
+│  🏆  DataPulse Analytics Agent                              │
+│    Source: tests/fixtures/good_card.json                    │
+│                                                             │
+│    Score: 88.0 / 100   (88%)   Grade:  A                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Installation
+
+```bash
+pip install agentcard-disco
+```
+
+For AI-assisted scoring (`--deep`):
+
+```bash
+pip install "agentcard-disco[deep]"
+```
+
+---
+
+## Quick start
+
+```bash
+# Score a local card
+agentcard-disco score ./agent-card.json
+
+# Score from a URL
+agentcard-disco score https://api.example.com/.well-known/agent-card.json
+
+# + AI quality analysis (requires GEMINI_API_KEY in .env)
+agentcard-disco score ./agent-card.json --deep
+
+# Export report as JSON or Markdown
+agentcard-disco score ./agent-card.json --format json --output report.json
+agentcard-disco score ./agent-card.json --format markdown --output report.md
+
+# CI gate — exit 1 if score is below 70%
+agentcard-disco score ./agent-card.json --fail-under 70
+
+# Get improvement suggestions only
+agentcard-disco suggest ./agent-card.json --priority high
+
+# Compare two cards side-by-side
+agentcard-disco compare ./v1.json ./v2.json
+```
+
+---
+
+## Scoring dimensions
+
+| Dimension | Points | What it measures |
+|-----------|-------:|-----------------|
+| Metadata Richness | 0–30 | Description length, tags, examples, provider info |
+| Semantic Specificity | 0–30 | Filler-word ratio, skill distinctness, action-verb density |
+| Search Alignment | 0–20 | Tag and keyword coverage vs A2A registry query vocabulary |
+| Completeness | 0–20 | SemVer, capabilities, auth declaration, protocol version |
+| AI Quality *(--deep)* | 0–20 | Categorical quality judgments via Gemini |
+
+**Grade scale:**
+
+| Grade | Score |
+|-------|-------|
+| A | 85–100% |
+| B | 70–84% |
+| C | 50–69% |
+| D | 30–49% |
+| F | 0–29% |
+
+---
+
+## AI scoring setup (`--deep`)
+
+1. Install the deep extra: `pip install "agentcard-disco[deep]"`
+2. Get a free Gemini API key at https://aistudio.google.com/app/apikey
+3. Add it to a `.env` file in your working directory:
+
+```env
+GEMINI_API_KEY="AIza..."
+```
+
+4. Run with `--deep`:
+
+```bash
+agentcard-disco score ./agent-card.json --deep
+```
+
+---
+
+## Python API
+
+```python
+from agentcard_disco.parser import load
+from agentcard_disco.scoring.engine import score
+
+card = load("agent-card.json")        # also accepts http(s):// URLs
+report = score(card)                  # Tier 1 only
+report = score(card, deep=True)       # + AI analysis
+
+print(report.grade.value)            # "A", "B", ...
+print(report.percentage)             # 88.0
+print(report.total_score)            # 88.0
+
+for suggestion in report.all_suggestions:
+    print(suggestion.priority, suggestion.field, suggestion.message)
+```
+
+---
+
+## Commands
+
+### `score`
+
+```
+agentcard-disco score SOURCE [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--deep` | off | Enable Tier 2 AI analysis (+20 pts) |
+| `--format` | terminal | `terminal`, `json`, or `markdown` |
+| `--output FILE` | stdout | Write output to file |
+| `--fail-under SCORE` | — | Exit 1 if percentage < SCORE |
+| `--no-suggestions` | off | Hide suggestions table |
+| `--no-detail` | off | Hide per-dimension details |
+
+### `suggest`
+
+```
+agentcard-disco suggest SOURCE [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--priority` | all | Filter: `all`, `high`, `medium`, `low` |
+| `--format` | terminal | `terminal` or `json` |
+| `--limit N` | 20 | Max suggestions to show |
+| `--deep` | off | Include AI suggestions |
+
+### `compare`
+
+```
+agentcard-disco compare SOURCE SOURCE [SOURCE ...] [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--format` | terminal | `terminal` or `json` |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/chinemeze/agentcard-disco
+cd agentcard-disco
+pip install -e ".[deep]"
+pip install pytest pytest-cov mypy ruff
+
+# Run tests
+pytest tests/ -v
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/
+```
+
+---
+
+## License
+
+MIT

agentcard_disco-0.1.0/USAGE.md

@@ -0,0 +1,141 @@
+# agentcard-disco — Usage Guide
+
+Score and optimise A2A Agent Cards for discoverability.
+
+---
+
+## Installation
+
+```bash
+cd agentcard-disco
+
+# Tier 1 only (no AI, no API key needed)
+pip install -e .
+
+# Tier 1 + Tier 2 AI scoring
+pip install -e ".[deep]"
+```
+
+---
+
+## Configuration
+
+Copy the example below into `.env` at the project root.  
+Only needed if you want `--deep` AI scoring.
+
+```env
+GEMINI_API_KEY="your-key-here"
+```
+
+Get a free key at: https://aistudio.google.com/app/apikey
+
+---
+
+## Commands
+
+### `score` — full discoverability report
+
+```bash
+agentcard-disco score <source>
+```
+
+| Option | Description |
+|--------|-------------|
+| `--deep` | Enable Tier 2 AI analysis (+20 pts). Requires `GEMINI_API_KEY`. |
+| `--format terminal\|json\|markdown` | Output format (default: terminal) |
+| `--output FILE` | Write output to a file |
+| `--fail-under SCORE` | Exit code 1 if score % is below this (useful in CI) |
+| `--no-suggestions` | Hide the suggestions table |
+| `--no-detail` | Hide per-dimension check/fail details |
+
+**Examples:**
+
+```bash
+agentcard-disco score ./agent-card.json
+agentcard-disco score ./agent-card.json --deep
+agentcard-disco score ./agent-card.json --format json --output report.json
+agentcard-disco score ./agent-card.json --format markdown --output report.md
+agentcard-disco score ./agent-card.json --fail-under 70
+```
+
+---
+
+### `suggest` — improvement suggestions only
+
+```bash
+agentcard-disco suggest <source>
+```
+
+| Option | Description |
+|--------|-------------|
+| `--priority all\|high\|medium\|low` | Filter by priority (default: all) |
+| `--format terminal\|json` | Output format (default: terminal) |
+| `--limit N` | Max number of suggestions to show (default: 20) |
+| `--deep` | Include AI-powered suggestions |
+
+**Examples:**
+
+```bash
+agentcard-disco suggest ./agent-card.json
+agentcard-disco suggest ./agent-card.json --priority high
+agentcard-disco suggest ./agent-card.json --format json
+```
+
+---
+
+### `compare` — side-by-side comparison
+
+```bash
+agentcard-disco compare <source1> <source2> [source3 ...]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--format terminal\|json` | Output format (default: terminal) |
+
+**Examples:**
+
+```bash
+agentcard-disco compare ./card-a.json ./card-b.json
+agentcard-disco compare ./v1.json ./v2.json ./v3.json
+```
+
+---
+
+## Scoring
+
+| Dimension | Points | Tier |
+|-----------|-------:|------|
+| Metadata Richness | 0–30 | 1 |
+| Semantic Specificity | 0–30 | 1 |
+| Search Alignment | 0–20 | 1 |
+| Completeness | 0–20 | 1 |
+| AI Quality (`--deep`) | 0–20 | 2 |
+
+**Grade scale** (based on %):
+
+| Grade | Range |
+|-------|-------|
+| A | 85–100% |
+| B | 70–84% |
+| C | 50–69% |
+| D | 30–49% |
+| F | 0–29% |
+
+---
+
+## Running Tests
+
+```bash
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+---
+
+## Source can be a local file or a URL
+
+```bash
+agentcard-disco score ./local-card.json
+agentcard-disco score https://api.example.com/.well-known/agent-card.json
+```