Metadata-Version: 2.4
Name: flatask
Version: 0.1.0
Summary: Build AI that answers questions from your Flatseek keyword indexes and Flatvec semantic indexes using any LLM.
Project-URL: Homepage, https://flatseek.io
Project-URL: Repository, https://github.com/flatseek/flatask
Project-URL: Issues, https://github.com/flatseek/flatask/issues
Project-URL: Documentation, https://flatask.demo.flatseek.io
Author-email: Judotens Budiarto <judotens@flatseek.io>
License: Apache-2.0
License-File: LICENSE
Keywords: context-engineering,knowledge,llm,rag,retrieval
Requires-Python: >=3.10
Requires-Dist: flatseek>=0.1.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == 'all'
Requires-Dist: google-genai>=0.3.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: gemini
Requires-Dist: google-genai>=0.3.0; extra == 'gemini'
Provides-Extra: ollama
Requires-Dist: httpx>=0.25.0; extra == 'ollama'
Requires-Dist: openai>=1.0.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: openrouter
Requires-Dist: openai>=1.0.0; extra == 'openrouter'
Provides-Extra: vllm
Requires-Dist: openai>=1.0.0; extra == 'vllm'
Description-Content-Type: text/markdown

<div align="center">

<img src="logo.svg" alt="Flatask" width="64" height="64">

# Flatask

**The knowledge runtime for Flatseek & Flatvec.**

<p align="center">
  <em>
Build AI that answers questions from your Flatseek keyword indexes and
Flatvec semantic indexes using any LLM.
  </em>
</p>

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![Tests](https://github.com/flatseek/flatask/workflows/Test/badge.svg)](https://github.com/flatseek/flatask/actions)
[![PyPI version](https://img.shields.io/pypi/v/flatask.svg)](https://pypi.org/project/flatask/)

**Docs:** https://flatseek.io/docs/flatask
&nbsp;&middot;&nbsp;
**Flatseek:** https://github.com/flatseek/flatseek
&nbsp;&middot;&nbsp;
**Flatvec:** https://github.com/flatseek/flatvec
&nbsp;&middot;&nbsp;
**Flattune:** https://github.com/flatseek/flattune

</div>

---

# 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.

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

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

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

Or directly from the CLI:

```bash
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

```bash
pip install flatask
```

Optional providers:

```bash
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

```python
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:

```bash
# 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:

```bash
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:

```bash
pytest tests/ -v
```

---

# License

Apache 2.0. See **LICENSE**.