priorart

Prior art scanner for ideas. Searches GitHub repositories and Hacker News discussions to assess how crowded a space is, then produces a Reality Signal score (0–100).

Installation

pip install priorart

Or with uv:

uv add priorart

Usage

# Basic scan (table output)
priorart scan 'AI personal finance tracker'

# JSON output
priorart scan 'AI personal finance tracker' --format json

# Markdown output (same format as GitHub Action comment)
priorart scan 'AI personal finance tracker' --format markdown

# Limit to specific sources
priorart scan 'AI personal finance tracker' --sources hn
priorart scan 'AI personal finance tracker' --sources github,hn

# With explicit GitHub token
priorart scan 'AI personal finance tracker' --github-token ghp_...

The GITHUB_TOKEN environment variable is used automatically if set:

export GITHUB_TOKEN=ghp_...
priorart scan 'AI personal finance tracker' --format json

Output formats

JSON (--format json)

{
  "query": "AI personal finance tracker",
  "queries": ["AI personal finance tracker", "AI personal finance"],
  "sources": [
    {
      "type": "github",
      "results": [
        {
          "name": "org/repo",
          "stars": 1234,
          "description": "...",
          "url": "https://github.com/org/repo",
          "updated": "2024-01-01",
          "language": "Python"
        }
      ]
    },
    {
      "type": "hn",
      "results": [
        {
          "title": "...",
          "points": 42,
          "comments": 17,
          "url": "https://news.ycombinator.com/item?id=...",
          "date": "2024-03-01"
        }
      ]
    }
  ],
  "signal": {
    "score": 45,
    "verdict": "MODERATE",
    "breakdown": {
      "github": 30,
      "hn": 15
    }
  },
  "meta": {
    "timestamp": "2026-03-07T00:00:00+00:00",
    "version": "0.1.0"
  }
}

Markdown (--format markdown)

Produces the same Markdown comment format used by the prior-art-scan GitHub Action.

Table (--format table)

Plain-text table for terminal output (default).

Reality Signal

The Reality Signal (0–100) reflects how crowded the solution space is:

The score is composed of:

• GitHub component (0–60): number of repos found + max star count
• HN component (0–40): number of discussions found + max point count

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src tests

Package structure

src/priorart/
├── __init__.py       # version
├── scanner.py        # orchestrator + query builder
├── scoring.py        # reality signal computation
├── formatters.py     # JSON, markdown, table output
├── cli.py            # typer CLI entry point
└── sources/
    ├── __init__.py
    ├── github.py     # GitHub repository search
    └── hn.py         # Hacker News search (Algolia API)