The knowledge runtime for Flatseek & Flatvec.
Build AI that answers questions from your Flatseek keyword indexes and Flatvec semantic indexes using any LLM.
GitHub: https://github.com/flatseek/flatask · Organization: https://github.com/flatseek
Part of the Flatseek ecosystem
Flatseek (Keyword Search) • Flatvec (Vector Search) • Flatask (RAG Runtime) • Flatrun (LLM Inference Runtime) • Flatweight (AI Model Storage) • Flattune (LLM Fine-Tuning) • Flatlens (Data Visualization)
Flatask understands diverse natural language patterns and handles mixed queries seamlessly:
flatask --llm "openai:gpt4" chat "https://huggingface.co/datasets/flatseek/public-dataset/resolve/main/500k-actors.fsk"
╔════════════════════════════════════════════════════╗
║ Flatask Chat (interactive mode) ║
║ Index: 500k-actors.fsk ║
║ Data: actors Fields: primaryname, birthyear, ║
║ deathyear, primaryprofession, knownfortitle ║
║ Conversation: cli-chat ║
╚════════════════════════════════════════════════════╝
You> hi
Assistant> Hi there! How can I help you today?
You> What fields are available?
Assistant> Fields in this index (5 total):
- primaryname, birthyear, deathyear, primaryprofession, knownfortitle
You> Tell me about Tom Hanks.
Assistant> Found 1 results:
1. Tom Hanks | Birthyear: 1956 | Knownfortitle: Forrest Gump
You> Actors with Chris in their name.
Assistant> Chris Farley (1964), Chris O'Donnell (1970), Chris Tucker (1971), ...
You> Show the oldest actors.
Assistant> Fred Astaire, Humphrey Bogart, James Cagney (all born 1899)
You> I'm looking for someone who starred in Titanic.
Assistant> Found 132 results:
1. Kate Winslet (1975) | actress
2. Billy Zane (1966) | actor
3. Leonardo DiCaprio (1974) | actor
...
You> How many actors were born after 1990?
Assistant> 31269
You> What is the average birth year?
Assistant> Distribution of birth years (top 10):
- 1980: 9244 items
- 1981: 9014 items
...Flatask automatically:
- Understands natural language questions
- Plans the optimal retrieval strategy
- Chooses keyword, semantic, or hybrid retrieval
- Builds optimized context for the LLM
- Generates grounded answers
- Includes citations back to the original documents
The same workflow is available from Python.
from flatseek import Flatseek
from flatvec import Flatvec
from flatask import Flatask
seek = Flatseek("./movies")
vec = Flatvec("./movies")
app = Flatask(
seek=seek,
vec=vec,
llm="openai:gpt-4o"
)
response = app.ask(
"Top 5 romance movies released after 2020"
)
print(response.text)
print(response.citations)Large Language Models are excellent at generating language, but they don't know your data.
Building Retrieval-Augmented Generation (RAG) systems often means stitching together multiple libraries for retrieval, prompt engineering, context management, reranking, citations, analytics, conversation history, and LLM providers.
For many applications, that infrastructure becomes more complicated than the AI feature itself.
Most applications don't need autonomous agents—they simply need accurate, grounded answers backed by their own knowledge.
Flatask is the runtime between retrieval and generation.
Instead of building an entire RAG pipeline yourself, Flatask sits on top of Flatseek and Flatvec, orchestrating retrieval, context engineering, analytics, and LLM generation through a single interface.
| Traditional RAG | Flatask | |
|---|---|---|
| Retrieval | Multiple libraries | Flatseek + Flatvec |
| Query Planning | Manual | Automatic |
| Hybrid Retrieval | Custom implementation | Built-in |
| Context Engineering | Manual | Automatic |
| Prompt Construction | Manual | Automatic |
| Citations | Custom implementation | Built-in |
| Analytics | Separate pipeline | Built-in |
| LLM Providers | Provider-specific | Unified interface |
Flatask and Flattune solve different problems.
Flatask uses Retrieval-Augmented Generation (RAG).
Your knowledge stays inside Flatseek and Flatvec indexes. Whenever a question is asked, Flatask retrieves only the relevant information, builds optimized context, and asks the LLM to generate an answer.
Question
│
▼
Flatseek / Flatvec
│
Retrieve Context
│
▼
LLM
│
▼
Grounded Answer
Flattune takes a different approach.
Instead of retrieving knowledge at runtime, Flattune converts knowledge into training datasets and fine-tunes a new language model.
Knowledge
│
▼
Flattune
│
Dataset Generation
│
▼
Supervised Fine-Tuning
│
▼
Specialized LLM
Choose Flatask when:
- knowledge changes frequently
- answers should include citations
- the latest data should always be available
- multiple LLMs should share the same knowledge
Choose Flattune when:
- the model should learn domain expertise
- writing style and behavior matter
- inference should work without retrieval
- you want a specialized standalone model
Many production systems use both.
Flattune teaches the model.
Flatask gives the model access to your latest knowledge.
User Question
│
▼
Query Planner
│
▼
Retrieval Orchestrator
┌──────────────┐
▼ ▼
Flatseek Flatvec
Keyword Search Semantic Search
└──────┬───────┘
▼
Context Builder
▼
Prompt Builder
▼
Any LLM
▼
Grounded Answer + Citations
Flatask never owns knowledge.
- Flatseek owns keyword retrieval.
- Flatvec owns semantic retrieval.
- Flatask owns context engineering and grounded generation.
| Capability | Description |
|---|---|
| Grounded Q&A | Generate answers backed by retrieved knowledge |
| Automatic Query Planning | Convert natural language into optimized retrieval plans |
| Hybrid Retrieval | Combine keyword and semantic retrieval automatically |
| Context Engineering | Build optimized context windows for LLMs |
| Grounded Generation | Generate answers using retrieved knowledge |
| Citation Support | Link every answer back to the original documents |
| Conversation Memory | Multi-turn conversations with contextual retrieval |
| Streaming Responses | Stream answers as they are generated |
| Read-only Analytics | Count, sum, average, min/max, percentiles, histograms |
| Interactive CLI | Colored input, readline history, auto-retry, schema preview |
| Multiple LLM Providers | OpenAI, Anthropic, Gemini, Ollama, LM Studio, OpenRouter |
| Python Library | Embed directly into existing applications |
| CLI | One-liner ask and multi-turn chat modes |
| Remote Knowledge | Query HTTP-hosted Flatseek indexes without downloading them |
pip install flataskOptional providers:
pip install flatask[openai]
pip install flatask[anthropic]
pip install flatask[gemini]
pip install flatask[ollama]
pip install flatask[all]Requirements:
- Python 3.10+
- Flatseek
- Flatvec (optional)
from flatseek import Flatseek
from flatvec import Flatvec
from flatask import Flatask
seek = Flatseek("./data")
vec = Flatvec("./vectors")
app = Flatask(
seek=seek,
vec=vec,
llm="openai:gpt-4o"
)
response = app.ask(
"What are the top rated action movies after 2015?"
)
print(response.text)
print(response.citations)Instead of writing Flatseek query syntax manually, simply ask questions.
| Question | Retrieval Plan |
|---|---|
| Top 5 actors born after 2000 | primaryprofession:actor + birthyear >= 2000 |
| Movies based on book or novel | overview:(book OR novel) |
| Romance movies after 2020 | genres:Romance + release_date >= 2020 |
| Average movie rating | Aggregate statistics |
| Birth year distribution | Histogram aggregation |
Flatask automatically determines whether your question requires:
- Keyword retrieval
- Semantic retrieval
- Hybrid retrieval
- Aggregations
- Statistics
- Histograms
- Analytics
- Grounded LLM generation
Not every question requires an LLM.
Flatask includes lightweight read-only analytics directly on Flatseek indexes.
Supported operations include:
- Count
- Sum
- Average
- Min / Max
- Percentiles
- Top Values
- Group By
- Statistics
- Histogram
- Distribution
- Pivot Tables
- Markdown Reports
Analytics results can optionally be summarized by an LLM to produce natural-language insights.
| Provider | Supported |
|---|---|
| OpenAI | ✅ |
| Anthropic Claude | ✅ |
| Google Gemini | ✅ |
| Ollama | ✅ |
| LM Studio | ✅ |
| OpenRouter | ✅ |
| OpenAI-compatible APIs | ✅ |
Ask a single question and get an answer:
# Local index
flatask ask ./movies "top rated romance movies after 2020"
# Remote .fsk file (auto-downloaded)
flatask ask https://huggingface.co/datasets/flatseek/public-dataset/resolve/main/500k-actors.fsk \
"how many actors were born in the 90s"
# Dry-run: see the generated query without executing
flatask ask ./movies "top action movies after 2015" --dry-runStart a chat session with the index — ask multiple questions, navigate history with arrow keys:
flatask chat ./movies
# With specific LLM
flatask --llm openai:gpt-4o chat ./actors
# Continue a conversation
flatask chat ./actors --conversation my-sessionIn interactive mode:
- Up/Down arrows — navigate command history (persisted in
~/.flatask/chat_history) - Ctrl+C — interrupt current request (prompts again)
- Ctrl+D — exit
- Schema displayed at start — see available fields before querying
- Auto-retry on transient server errors (529 overload, timeout, etc.)
What makes this work:
- Keyword pre-detection — catches "siapa", "who", "show", "tell me" → list mode
- Year extraction — "80an" →
birthyear >= 1980 AND birthyear <= 1989 - Multi-filter — "lahir setelah X dan meninggal sebelum Y" → combined filters
- Intent recognition — "hi" → chat mode, "fields" → fields mode, numbers → aggregate
- Smart defaults — small LLM models get help from regex pre-extraction
Flatask automatically converts natural language to optimized queries:
| Question | Generated Query |
|---|---|
| how many actors born in the 90s | birthyear:>=1990 AND birthyear:<=1999 (mode: count) |
| actors in their 50s | birthyear:>=1967 AND birthyear:<=1976 (mode: aggregate) |
| top 5 action movies | genres:Action + sort (mode: query) |
| who directed terminator | title:Terminator (mode: query) |
| what fields exist in this index | field listing (mode: fields) |
| thanks | conversational (mode: chat) |
Query modes:
- query — keyword/semantic search for specific things
- aggregate/count — fast count without stats computation
- aggregate/stats — min, max, avg, sum
- aggregate/terms — top values distribution
- fields — return field/column listing
- chat — conversational questions, greetings, non-data queries
--dry-run prints the generated retrieval plan without executing the search, making it useful for debugging query planning.
| Guide | Description |
|---|---|
| CLI Reference | Command-line reference |
| Query Modes | Query planning modes |
| Quick Start | Build your first AI application |
| Retrieval Planning | Natural language to Flatseek queries |
| Context Engineering | Context building strategies |
| Prompt Templates | Prompt customization |
| Hybrid Retrieval | Flatseek + Flatvec |
| Analytics | Statistics and aggregations |
| LLM Providers | Provider configuration |
| Python Library | Complete Python API |
| Architecture | Internal runtime |
| Examples | End-to-end examples |
PRs are welcome.
Run all tests:
pytest tests/ -vApache 2.0. See LICENSE.