ByteScribe

Automated research and study guide synthesizer. Enter a topic, get a structured Markdown study guide sourced from live web articles.

 ___          _        ____          _ _
| __ )  _   _| |_ ___ / ___| ___ _ _(_) |__   ___
|  _ \ | | | | __/ _ \___ \/ __| '__| | '_ \ / _ \
| |_) || |_| | ||  __/___) ) (__| |  | | |_) |  __/
|____/  \__, |\__\___|____/ \___|_|  |_|_.__/ \___|
         |___/
[ Automated Research & Study Guide Synthesizer ]

How it works

ByteScribe runs a 3-step pipeline:

1. Search — queries the web for the top articles on your topic (Tavily API)
2. Scrape — extracts clean article text from each URL (trafilatura)
3. Generate — synthesizes everything into a structured study guide (Groq / Llama 3.3 70B)

Output is saved to .tmp/study_guide.md with sections for Overview, Core Concepts, Key Terms, Subtopics, Practical Applications, Key Takeaways, and Further Reading.

Setup

1. Clone and install dependencies

git clone <repo-url>
cd ByteScribe
pip install -r requirements.txt

2. Get free API keys

Key	Where to get it	Free tier
TAVILY_API_KEY	app.tavily.com	1,000 searches/month
GROQ_API_KEY	console.groq.com	~14,400 requests/day

3. Add keys to .env

TAVILY_API_KEY=tvly-...
GROQ_API_KEY=gsk_...

Usage

Run each step from the project root, substituting your topic:

# Step 1 — find articles
python tools/search_topic.py --topic "your topic here"

# Step 2 — scrape each URL (run once per URL in .tmp/search_results.json)
python tools/scrape_article.py --url "https://..." --delay 1

# Step 3 — generate study guide
python tools/generate_study_guide.py --topic "your topic here"

The study guide is saved to .tmp/study_guide.md.

See workflows/bytescribe.md for the full orchestration SOP including error handling and edge cases.

Project structure

tools/
  banner.py                 # Shared CLI banner
  search_topic.py           # Step 1: web search via Tavily
  scrape_article.py         # Step 2: article extraction via trafilatura
  generate_study_guide.py   # Step 3: synthesis via Groq
  export_to_google_docs.py  # Optional: push to Google Docs
workflows/
  bytescribe.md             # End-to-end SOP
  export_to_google_docs.md  # Google Cloud setup guide (optional)
.tmp/                       # Runtime output (gitignored)

Agent compatibility

ByteScribe follows the WAT framework — workflows are plain Markdown, tools are plain CLI scripts. Any agentic coding assistant that can read files and run shell commands can orchestrate this project the same way Claude does.

To use with a different agent, create the equivalent instructions file for that agent (e.g., GEMINI.md for Gemini) pointing it at workflows/bytescribe.md. The pipeline itself is agent-agnostic.

Built with

• Tavily — web search API
• trafilatura — article text extraction
• Groq — fast inference (Llama 3.3 70B)