Flatask

The knowledge runtime for Flatseek & Flatvec.

Build AI that answers questions from your Flatseek keyword indexes and Flatvec semantic indexes using any LLM.

Docs: https://flatseek.io/docs/flatask  ·  Flatseek: https://github.com/flatseek/flatseek  ·  Flatvec: https://github.com/flatseek/flatvec  ·  Flattune: https://github.com/flatseek/flattune

See it work

Ask questions directly against your Flatseek keyword indexes or Flatvec semantic indexes. Flatask plans retrieval, builds optimized context, invokes your preferred LLM, and returns grounded answers with citations.

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"
)

answer = app.ask(
    "Top 5 romance movies released after 2020"
)

print(answer.text)
print(answer.citations)

Or directly from the CLI:

flatask ask \
  https://huggingface.co/datasets/flatseek/public-dataset/resolve/main/1.2M-movies.fsk \
  "movies based on book or novel"

Flatask automatically:

• Understands natural language questions
• Plans the optimal retrieval strategy
• Executes keyword and/or semantic retrieval
• Builds optimized context for the LLM
• Generates grounded answers
• Includes citations back to the original documents

The problem

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.

What Flatask does differently

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.

RAG vs Fine-Tuning

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.

Architecture

                 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.

Core capabilities

Installation

PyPI

pip install flatask

Optional 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)

Quick start

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)

Natural language retrieval

Instead of writing Flatseek query syntax manually, simply ask questions.

Flatask automatically determines whether your question requires:

• Keyword retrieval
• Semantic retrieval
• Hybrid retrieval
• Aggregations
• Statistics
• Histograms
• Analytics
• Grounded LLM generation

Built-in analytics

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.

Supported LLM providers

CLI

One-liner mode

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-run

Interactive mode

Start 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-session

In 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.)

Query refinement

Flatask automatically converts natural language to optimized queries:

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.

Full documentation

Contributing

PRs are welcome.

Run all tests:

pytest tests/ -v

License

Apache 2.0. See LICENSE.