flatask 0.1.0

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

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.

	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

---

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

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

---

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.

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

---

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

Provider	Supported
OpenAI	✅
Anthropic Claude	✅
Google Gemini	✅
Ollama	✅
LM Studio	✅
OpenRouter	✅
OpenAI-compatible APIs	✅

---

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:

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.

---

Full documentation

Guide	Description
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
CLI Reference	Command-line reference
Architecture	Internal runtime
Examples	End-to-end examples

---

Contributing

PRs are welcome.

Run all tests:

pytest tests/ -v

---

License

Apache 2.0. See LICENSE.