PyPackage Oracle

Describe what you want to build in plain English.
Get the best Python package for it — backed by real evidence from Stack Overflow, blogs, PyPI, and GitHub.

---

What it does

PyPackage Oracle takes a plain-English task description and returns an opinionated, evidence-backed recommendation for the best Python library to use — no hallucinated guesses, just real search results synthesized by AI.

"parse markdown with async support"
         ↓
   ┌─────────────────────────────────────────┐
   │  SerpApi searches (4 sources)           │
   │  • Stack Overflow  • Blogs & tutorials  │
   │  • PyPI packages   • GitHub discussions │
   └─────────────────────────────────────────┘
         ↓
   GPT-4o synthesis (OpenAI)
         ↓
   Ranked recommendation + pros/cons + citations

What you get:

• Top pick — the best package with pros, cons, and install command
• Alternatives — 2 runner-ups with specific use cases where they win
• Watch out — a concrete pitfall or gotcha to be aware of
• Verdict — an opinionated 2-3 sentence summary of the landscape
• Sources — all 20 search results used as evidence, expandable

---

Tech Stack

Layer	Technology
UI	Streamlit
Search	SerpApi (Google Search engine)
AI synthesis	OpenAI GPT-4o
Language	Python 3.10+

---

Setup

1. Clone and install

git clone https://github.com/everestkc/PyPackageOracle.git
cd PyPackageOracle
pip install -r requirements.txt

2. Add your API keys

Create a .env file in the project root:

SERPAPI_KEY=your_serpapi_key_here
OPENAI_API_KEY=your_openai_key_here

• SerpApi key — free tier at serpapi.com
• OpenAI key — get one at platform.openai.com

3. Run

streamlit run app.py

Open http://localhost:8501 in your browser.

---

Deploy to Streamlit Cloud

1. Push this repo to GitHub
2. Go to share.streamlit.io → New app
3. Select your repo and set main file to app.py
4. Under Advanced settings → Secrets, paste:

SERPAPI_KEY = "your_serpapi_key"
OPENAI_API_KEY = "your_openai_key"

5. Click Deploy — you get a public URL instantly

---

How it works

oracle.py runs 4 targeted Google searches via SerpApi per query:

# Stack Overflow — real developer usage patterns
{"engine": "google", "q": f"{query} python site:stackoverflow.com"}

# Blogs — community recommendations
{"engine": "google", "q": f"best python library for {query} 2024"}

# PyPI — package discovery
{"engine": "google", "q": f"{query} python pypi package"}

# GitHub — maintainer and contributor opinions
{"engine": "google", "q": f"{query} python site:github.com discussions OR README"}

All 20 results (5 per source) are passed as grounded evidence to GPT-4o, which returns a structured JSON recommendation. The UI surfaces this as a winner card, alternatives, watchout banner, verdict, and a collapsible source list.

---

Project structure

PyPackageOracle/
├── app.py           # Streamlit UI — dark editorial theme, all rendering logic
├── oracle.py        # Core logic — SerpApi searches + GPT-4o synthesis
├── requirements.txt
└── .env             # API keys (never commit this)

---

Requirements

serpapi>=0.1.0
openai
streamlit>=1.32.0
python-dotenv

---

Built with SerpApi · OpenAI · Streamlit