crewscore 0.2.0__tar.gz

crewscore-0.2.0/.github/workflows/crewscore-selftest.yml

@@ -0,0 +1,46 @@
+# Self-test for the composite CrewScore action in this repo.
+# Installs from github.action_path so it works before PyPI publish.
+name: CrewScore Self-Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  selftest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Score sample prompt (smoke, threshold 0)
+        id: score
+        uses: ./
+        with:
+          prompt-file: examples/sample-prompt.md
+          threshold: "0"
+
+      - name: Assert score and tier outputs parse
+        run: |
+          echo "score=${{ steps.score.outputs.score }}"
+          echo "tier=${{ steps.score.outputs.tier }}"
+          python -c "
+          import sys
+          score = int(sys.argv[1])
+          tier = sys.argv[2]
+          assert 0 <= score <= 100, score
+          assert tier, 'tier output empty'
+          print(f'OK score={score} tier={tier!r}')
+          " "${{ steps.score.outputs.score }}" "${{ steps.score.outputs.tier }}"
+
+      - name: Threshold gate fails when score is below threshold
+        run: |
+          set +e
+          crewscore test --prompt-file examples/sample-prompt.md --json --threshold 50
+          EXIT=$?
+          set -e
+          if [ "$EXIT" -ne 2 ]; then
+            echo "Expected exit code 2 for bare sample prompt under threshold 50, got $EXIT"
+            exit 1
+          fi
+          echo "Threshold failure behaved as expected (exit 2)"

crewscore-0.2.0/.github/workflows/example-ci.yml

@@ -0,0 +1,46 @@
+# Documented copy-paste example for consumers.
+#
+# In your own repo, prefer the published tag:
+#   uses: shmindmaster/crewscore@v1
+#
+# When developing this monorepo (or a fork), local path works:
+#   uses: ./
+#
+# Point prompt-file at your agent system prompt. The sample path below is only
+# for illustration; examples/sample-prompt.md intentionally scores low.
+#
+# workflow_dispatch only so this example does not fail default CI on the bare
+# sample prompt. Use crewscore-selftest.yml for green self-tests.
+name: CrewScore CI Example
+
+on:
+  workflow_dispatch:
+
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Published action (recommended for consumer repos):
+      # - name: CrewScore
+      #   uses: shmindmaster/crewscore@v1
+      #   with:
+      #     prompt-file: agents/system-prompt.md
+      #     threshold: "50"
+      #     # explain: "true"
+
+      # Local composite action (this repo / monorepo self-check):
+      - name: CrewScore
+        id: crewscore
+        uses: ./
+        with:
+          prompt-file: examples/sample-prompt.md
+          threshold: "50"
+
+      - name: Use score outputs
+        if: always()
+        run: |
+          echo "score=${{ steps.crewscore.outputs.score }}"
+          echo "tier=${{ steps.crewscore.outputs.tier }}"

crewscore-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.sqlite3
+agent-guard-report-*.html
+.DS_Store
+
+.superpowers/
+.worktrees/
+

crewscore-0.2.0/AGENTS.md

@@ -0,0 +1,72 @@
+# CrewScore — agent instructions
+
+## What this is
+
+Offline CLI that **structurally** scores AI agent system prompts for production-readiness signals (injection defense, hallucination policy, citations, cost limits, human gates, safe-stop, audit, compliance), applies fix patterns, and runs a non-technical AI vendor checklist.
+
+Public brand: **CrewScore** · Domain: **https://crewscore.ai** · PyPI: **`crewscore`** · Repo: **shmindmaster/crewscore**
+
+It does **not** (yet) run live adversarial LLM attacks or parse LangGraph/CrewAI runtimes.
+
+## Stack
+
+- Python 3.11+
+- click + rich
+- hatchling packaging
+- pytest
+
+## Commands
+
+```bash
+# install (editable)
+pip install -e ".[dev]"
+
+# score a prompt
+crewscore test --prompt "You are a helpful assistant..."
+crewscore test --prompt-file ./system-prompt.md
+crewscore test --prompt-file ./system-prompt.md --json
+crewscore test --prompt-file ./system-prompt.md --json --threshold 50
+
+# apply guardrail patterns
+crewscore fix --prompt-file ./system-prompt.md
+crewscore fix --prompt-file ./system-prompt.md --apply
+crewscore fix --prompt-file ./system-prompt.md --output ./guarded.md --json
+
+# vendor checklist
+crewscore assess-vendor --name "Acme AI" --answers "y,y,n,dk,y,y,n,y,n,y" --json
+
+# tests
+pytest
+```
+
+Legacy CLI entry point `agent-guard` still maps to the same `crewscore.cli:main` after install.
+
+## Layout
+
+```
+crewscore/
+  cli.py                 # click entry (test, fix)
+  scoring.py             # shared result model / tiers
+  vendor_scorecard.py    # assess-vendor command
+  scorers/
+    structural_analysis.py
+    fix_patterns.py
+tests/
+index.html               # static browser demo (client-side structural scan)
+```
+
+## Product constraints
+
+- Prefer honest capability claims over roadmap theater.
+- Structural scores are pattern matches on prompt text, not proof of runtime behavior.
+- Keep the package dependency-light (no LLM SDKs required for the core path).
+- Fame follows usefulness: explainable findings, fix, CI gate before launch theater.
+- Breaking CLI flags are acceptable if all docs and tests update in the same change.
+- Never document `pip install agent-guard` as *this* product (that PyPI name is taken by another package).
+
+## Do not
+
+- Reintroduce fake `--langgraph` / `--crewai` loaders or adversarial mode stubs without real implementations.
+- Link to non-existent report hosts or wrong GitHub/PyPI names.
+- Add empty `examples/` / `evaluator/` / `patterns/` directories without content.
+- Overclaim “production safety certification” or “7 regulated systems” beyond structural scanning.

crewscore-0.2.0/CNAME

@@ -0,0 +1 @@
+crewscore.ai

crewscore-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarosh Hussain / Pendoah
+
+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.

crewscore-0.2.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: crewscore
+Version: 0.2.0
+Summary: CrewScore — offline structural production-readiness scorecard for AI agent system prompts.
+Project-URL: Homepage, https://crewscore.ai
+Project-URL: Repository, https://github.com/shmindmaster/crewscore
+Project-URL: Issues, https://github.com/shmindmaster/crewscore/issues
+Project-URL: Documentation, https://github.com/shmindmaster/crewscore#readme
+Author-email: Sarosh Hussain <sarosh@pendoah.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,crewscore,evaluation,governance,guardrails,llm,production,safety,scorecard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# CrewScore
+
+### Structural production-readiness scorecard for AI agent system prompts
+
+**Site:** [crewscore.ai](https://crewscore.ai) · **Install:** `pip install crewscore`
+
+```
+$ pip install crewscore
+$ crewscore test --prompt "You are a helpful assistant that..."
+
+  CREWSCORE — Structural Production Readiness Report
+  ====================================================
+
+  Prompt Injection Resistance      [----------]   0/100  MISSING
+  Hallucination Guardrails         [----------]   0/100  MISSING
+  Source Citation Requirements     [----------]   0/100  MISSING
+  Cost Runaway Protection          [----------]   0/100  MISSING
+  Human-in-the-Loop Gates          [----------]   0/100  MISSING
+  Safe-Stop Behavior               [----------]   0/100  MISSING
+  Audit Trail & Provenance         [----------]   0/100  MISSING
+  Compliance Readiness             [----------]   0/100  MISSING
+
+  OVERALL SCORE:  0/100  NOT PRODUCTION READY
+```
+
+Score the **text** of your agent instructions. Fix gaps. Gate CI when scores drop.
+
+[Install](#install) · [Usage](#usage) · [Share](#share-your-score) · [How scoring works](#how-scoring-works) · [CI](#ci-integration) · [Limits](#what-this-is-and-is-not)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11+-green.svg)](https://python.org)
+[![PyPI](https://img.shields.io/badge/PyPI-crewscore-blue.svg)](https://pypi.org/project/crewscore/)
+
+</div>
+
+---
+
+## The problem
+
+You shipped an agent that works in a demo. Before production you still need to ask:
+
+- Does the prompt resist obvious injection / override language?
+- Does it forbid fabricating citations and force “I don’t know”?
+- Are writes, sends, and publishes gated on human approval?
+- Is there any cost, audit, or compliance language at all?
+
+Most teams never inspect those instructions systematically. **CrewScore** does a fast structural scan and can append proven guardrail patterns.
+
+---
+
+## What this is (and is not)
+
+| Is | Is not |
+|----|--------|
+| Offline structural scan of system-prompt text | Live adversarial LLM red-teaming |
+| Fix mode that appends guardrail sections | Proof that the runtime will obey the text |
+| JSON output + exit threshold for CI | LangGraph / CrewAI graph execution analysis |
+| Vendor checklist (`assess-vendor`) for procurement diligence | Independent security certification |
+
+Scores reflect **prompt-text signals**. They are a useful smoke test, not a guarantee of runtime safety.
+
+> **Name note:** PyPI package `agent-guard` is an unrelated third-party CrewAI monitoring library. This project is **CrewScore** (`pip install crewscore`). The CLI also accepts the legacy alias `agent-guard` after install.
+
+---
+
+## Install
+
+```bash
+pip install crewscore
+
+# from source (development)
+pip install -e ".[dev]"
+```
+
+No API key for structural mode.
+
+---
+
+## Usage
+
+### Score a system prompt
+
+```bash
+crewscore test --prompt "You are a customer service agent for..."
+crewscore test --prompt-file ./my-agent/system-prompt.md
+crewscore test --prompt-file ./my-agent/system-prompt.md --json
+crewscore test --prompt-file ./my-agent/system-prompt.md --json --threshold 50
+```
+
+`--threshold N` exits with code `2` when overall score is below `N` (CI gate).
+
+### Share your score
+
+Export a self-contained HTML report and an SVG badge after scoring:
+
+```bash
+crewscore test --prompt-file ./system-prompt.md --report report.html --badge crewscore.svg
+```
+
+Embed the badge in a README or PR description (path relative to your repo):
+
+```markdown
+![CrewScore](./crewscore.svg)
+```
+
+Or point CI at a committed badge path after generating it in a workflow step:
+
+```markdown
+![CrewScore](./badges/crewscore.svg)
+```
+
+Human mode also prints a one-line share blurb with your overall score and [crewscore.ai](https://crewscore.ai). Reports are structural-scan artifacts only — not runtime proof of safety.
+
+### Apply guardrail patterns
+
+```bash
+# print enhanced prompt
+crewscore fix --prompt-file ./system-prompt.md
+
+# write in place and show score delta
+crewscore fix --prompt-file ./system-prompt.md --apply
+
+# write to a new file
+crewscore fix --prompt-file ./system-prompt.md --output ./system-prompt-guarded.md
+
+# machine-readable summary
+crewscore fix --prompt-file ./system-prompt.md --apply --json
+```
+
+### Score an AI vendor (checklist)
+
+```bash
+crewscore assess-vendor --name "Acme AI" --answers "y,y,n,dk,y,y,n,y,n,y"
+crewscore assess-vendor --name "Acme AI" --answers "y,y,n,dk,y,y,n,y,n,y" --json
+```
+
+Answers are `y` / `n` / `dk` for each of 10 diligence questions.
+
+### Browser demo
+
+Open `index.html` locally (or on GitHub Pages) for a zero-install structural scan and vendor checklist UI (client-side only; not the CLI implementation).
+
+---
+
+## How scoring works
+
+Eight dimensions, equal weight, each 0–100:
+
+| Dimension | What the scanner looks for |
+|-----------|----------------------------|
+| Prompt Injection Resistance | Reject-override / do-not-reveal-system / jailbreak language |
+| Hallucination Guardrails | No fabrication, “I don’t know”, grounded-only claims |
+| Source Citation | Claims must cite sources / evidence |
+| Cost Runaway Protection | Token/budget/max-length limits |
+| Human-in-the-Loop Gates | Approval before send/write/publish |
+| Safe-Stop Behavior | Halt when evidence missing or uncertain |
+| Audit Trail | Log decisions / immutable trail language |
+| Compliance Readiness | HIPAA/SOC2/GDPR/EU AI Act style handling language |
+
+### Score tiers
+
+| Score | Verdict |
+|-------|---------|
+| 90–100 | PRODUCTION READY (structurally) |
+| 70–89 | SHIP WITH MONITORING |
+| 50–69 | NEEDS WORK |
+| 0–49 | NOT PRODUCTION READY |
+
+---
+
+## CI integration
+
+### Official GitHub Action (recommended)
+
+One YAML step — no manual pip ritual:
+
+```yaml
+# .github/workflows/crewscore.yml
+name: CrewScore
+on: [pull_request]
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: CrewScore
+        id: crewscore
+        uses: shmindmaster/crewscore@v1
+        with:
+          prompt-file: ./agents/system-prompt.md
+          threshold: "50"
+          # explain: "true"   # optional: matched vs missing signals
+      - name: Report
+        if: always()
+        run: |
+          echo "score=${{ steps.crewscore.outputs.score }}"
+          echo "tier=${{ steps.crewscore.outputs.tier }}"
+```
+
+**Inputs**
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `prompt-file` | yes | — | Path to the system prompt file |
+| `threshold` | no | `50` | Fail the step (exit 2) when overall score is below this |
+| `explain` | no | `false` | Pass `true` to include matched/missing signals |
+
+**Outputs:** `score` (0–100), `tier` (label string).
+
+The composite action installs CrewScore from the action path (`pip install "${{ github.action_path }}"`), so monorepo / pre-PyPI self-tests work with `uses: ./`.
+
+`uses: shmindmaster/crewscore@v1` requires a floating major tag `v1` on the release commit (in addition to the immutable `vX.Y.Z` tag). Maintainers create or move `v1` after each compatible release — see [docs/publish-checklist.md](docs/publish-checklist.md).
+
+See [`.github/workflows/example-ci.yml`](.github/workflows/example-ci.yml) for a documented consumer template and [`.github/workflows/crewscore-selftest.yml`](.github/workflows/crewscore-selftest.yml) for this repo’s smoke self-test.
+
+### CLI in CI
+
+```yaml
+# .github/workflows/crewscore-cli.yml
+name: CrewScore CLI
+on: [pull_request]
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install crewscore
+      - run: crewscore test --prompt-file ./agents/system-prompt.md --json --threshold 50
+```
+
+Or parse JSON yourself:
+
+```bash
+SCORE=$(crewscore test --prompt-file ./agents/system-prompt.md --json | jq '.overall')
+```
+
+---
+
+## Fix patterns
+
+When dimensions score below threshold, `crewscore fix` appends production-style guardrail sections for:
+
+- Injection defense
+- Anti-hallucination
+- Citation requirements
+- Cost governance
+- Human gates
+- Safe-stop
+- Audit trail
+- Compliance / data protection
+
+These are **prompt text templates**. Wire matching runtime controls (tool gates, logging, budgets) in your application.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/shmindmaster/crewscore.git
+cd crewscore
+pip install -e ".[dev]"
+pytest
+crewscore test --prompt "You are a helpful assistant"
+```
+
+See [AGENTS.md](AGENTS.md) for agent/contributor operating notes.
+
+---
+
+## Roadmap (not implemented yet)
+
+- Framework adapters that extract prompts from LangGraph / CrewAI / AutoGen graphs
+- Optional live adversarial testing (post-traction; not the default path)
+
+---
+
+## License
+
+MIT.