⚡ GraphSearch

Ask questions. Get grounded answers. One GraphQL endpoint.

Turn any pile of documents — PDFs, Markdown, plain text — into a typed,
introspectable Q&A API. Zero API keys, zero infrastructure to start.

Quickstart · Playground · API · Architecture · Roadmap · Contributing

"How do I get my money back?" finds the returns policy — no shared keywords, no API keys.

✨ Why GraphSearch?

🚀 Quickstart

pip install graphsearch-rag        # imports as `graphsearch`

graphsearch-ingest data/example_docs   # or your own .pdf / .md / .txt
graphsearch                            # → http://localhost:8000

That's it — no API keys, no services, no config. Prefer containers?

docker run -p 8000:8000 ghcr.io/mohithgowdak/graphsearch:latest

graphsearch not recognized? With pip install --user (Windows default when site-packages isn't writable), pip's Scripts folder may not be on PATH. Skip PATH entirely:

python -m graphsearch                            # start the server
python -m graphsearch.ingest data/example_docs   # ingest documents

🎮 The Playground

Open http://localhost:8000/ and test RAG with your own documents before writing a line of client code — paste text or drop files, ask questions, inspect ranked sources. Every action has a "Show the GraphQL" toggle revealing the exact query it runs, ready to copy into your app.

Prefer raw GraphQL? GraphiQL lives at http://localhost:8000/graphql.

🎚 Level up the pipeline

The default mode is fully offline (hashing-trick embeddings + extractive answers) so the whole pipeline runs anywhere, including CI. Upgrade each stage independently:

Real semantic search — still no API key (sentence-transformers, ~80 MB model, CPU):

pip install "graphsearch-rag[local]"
export GRAPHSEARCH_EMBEDDINGS=local    # $env:GRAPHSEARCH_EMBEDDINGS='local' on Windows
graphsearch-ingest data/example_docs   # re-ingest: embeddings are created at ingest time
graphsearch

LLM-generated answers with citations (OpenAI or Anthropic):

pip install "graphsearch-rag[anthropic]"   # or [openai]
export GRAPHSEARCH_LLM=anthropic           # or openai
export ANTHROPIC_API_KEY=sk-ant-...
graphsearch

Documents are embedded at ingest time — re-ingest after switching embedding backends. Full configuration reference: .env.example

🧩 GraphQL API

# Queries
answer(question: String!, topK: Int): Answer!      # RAG: retrieve + generate, with cited sources
search(query: String!, topK: Int): [Chunk!]!       # raw semantic search
documents(limit: Int = 20, offset: Int = 0): [Document!]!
document(id: ID!): Document

# Mutations
uploadDocument(content: String!, title: String, source: String): Document!
uploadFile(file: Upload!, title: String, source: String): Document!    # PDF/Markdown/text
deleteDocument(id: ID!): Boolean!

mutation {
  uploadDocument(
    content: "Support hours are 9am-5pm PST, Monday through Friday."
    title: "support-hours"
  ) { id chunkCount }
}

query {
  answer(question: "When is support available?") {
    text                                 # cites sources as [1], [2], ...
    sources { documentTitle text score }
  }
}

TypeScript? clients/typescript ships a fully-typed SDK generated straight from this schema — client.Answer({ question }), client.Search(...), etc. CI regenerates it on every push and fails the build if it drifts from the server.

🏗 Architecture

flowchart LR
    C([Client]) -->|"GraphQL"| S["FastAPI + Strawberry"]
    S --> R["RagService"]
    R --> CH["Chunker<br/>paragraph-aware"]
    R --> E["Embedder<br/>hash · local · OpenAI"]
    R --> V["VectorStore<br/>in-memory cosine"]
    R --> L["LLM<br/>extractive · OpenAI · Claude"]
    V <--> DB[("SQLite<br/>docs · chunks · vectors")]
    style S fill:#e10098,color:#fff
    style R fill:#1c1c28,color:#fff

Every pipeline stage is an abstract interface (Embedder, VectorStore, LLM) — new backends are drop-in additions, and several are up for grabs as good first issues.

🛠 Development

git clone https://github.com/mohithgowdak/graphsearch && cd graphsearch
pip install -e ".[dev]"
ruff check .          # lint
pytest -v             # 33 tests, all fully offline

🗺 Roadmap / good first issues

• Vector store backends: Qdrant, Weaviate, Redis/Valkey, pgvector, FAISS
• Embedding backends: Cohere, Voyage
• Streaming answers via GraphQL subscriptions
• Metadata tags + filters; hybrid keyword+vector search (SQLite FTS5)
• Auth (API keys / JWT) and rate limiting
• Query/embedding caching
• Auto-generated TypeScript client — see clients/typescript
• Evaluation harness + Prometheus metrics
• Advanced RAG: query rewriting, multi-hop retrieval, citation spans

Most of these are filed with implementation notes — grab one 👋

🤝 Contributing

Contributions are very welcome! CONTRIBUTING.md covers setup, the backend-authoring guide, and PR guidelines. Look for the good first issue label to get started.

📄 License

MIT — do whatever you want, just keep the notice.