# 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

```bash
pip install priorart
```

Or with `uv`:

```bash
uv add priorart
```

## Usage

```bash
# 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:

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

## Output formats

### JSON (`--format json`)

```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:

| Score | Verdict | Meaning |
|-------|---------|---------|
| 0–29 | 🟢 LOW | Greenfield opportunity or underserved niche |
| 30–60 | 🟡 MODERATE | Some existing solutions, differentiation needed |
| 61–100 | 🔴 HIGH | Crowded space, needs strong differentiator |

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

```bash
# 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)
```
