Lesson 6 of 6
Assemble the Command-Line Tool
Wrap the previous steps into one script that takes a document file and a question as arguments and prints an answer.
10 minAI Engineering
After this lesson, you will be able to turn the retrieval-augmented generation pipeline into a single command-line tool. You will write a script that takes a document file and a question as arguments, runs all the steps from reading the file to generating an answer, and prints the result. You will also learn how to handle missing arguments and how to make the tool configurable with command-line options.
Review the Pipeline
In the earlier lessons, you built several Python modules: vectorizer.py for building a vocabulary, retriever.py for retrieving top chunks, prompt_builder.py for building a prompt, and generator.py for generating an answer with a placeholder model. In lesson 5, you wrote a script called pipeline.py that used all these modules together. That script read a file, split it into chunks, built the vocabulary, retrieved chunks, built a prompt, and generated an answer. However, it only accepted a file path and a question as positional arguments, and it used fixed values for chunk size, overlap, and the number of retrieved chunks.
In this lesson, you will improve that script into a proper command-line tool. You will add options so the user can change the chunk size, overlap, and number of retrieved chunks without editing the code. You will also add better error handling so the tool gives a clear message if the user forgets an argument or if the file does not exist.
Refactor the Pipeline into a Function
Create a file called pipeline.py with the following code. This is similar to the pipeline.py from lesson 5, but the main logic is now inside a function called run_pipeline. This function takes the file path, question, chunk size, overlap, and top-k as arguments, and returns the generated answer. It does not print anything itself.
from vectorizer import build_vocabulary
from retriever import retrieve_top_chunks
from prompt_builder import build_prompt
from generator import generate_answer
def read_file(file_path):
with open(file_path, 'r', encoding='utf-8') as f:
return f.read()
def chunk_words(words, chunk_size, overlap):
chunks = []
start = 0
while start < len(words):
end = start + chunk_size
chunk = words[start:end]
chunks.append(' '.join(chunk))
start += chunk_size - overlap
return chunks
def run_pipeline(file_path, question, chunk_size=10, overlap=5, top_k=2):
text = read_file(file_path)
words = text.split()
chunks = chunk_words(words, chunk_size, overlap)
vocab = build_vocabulary(chunks)
top = retrieve_top_chunks(question, chunks, vocab, top_k=top_k)
prompt = build_prompt(question, top)
answer = generate_answer(prompt)
return answerNotice that run_pipeline has default values for chunk_size, overlap, and top_k, so you can call it with just a file and a question if you want the defaults. The read_file and chunk_words functions are the same as before. The pipeline now returns the answer instead of printing it, which makes it easier to use from other scripts or tests.
Create the Command-Line Tool
Now create a new file called cli.py with the following code. This file will contain the command-line interface logic, separate from the pipeline logic. Keeping the interface separate makes the code easier to test and reuse. It imports run_pipeline from the pipeline.py file you just created.
import argparse
from pipeline import run_pipeline
def main():
parser = argparse.ArgumentParser(
description='Answer a question based on a document using retrieval-augmented generation.'
)
parser.add_argument('file', help='path to the plain-text document')
parser.add_argument('question', help='the question to answer')
parser.add_argument('--chunk-size', type=int, default=10,
help='number of words per chunk (default: 10)')
parser.add_argument('--overlap', type=int, default=5,
help='number of overlapping words between chunks (default: 5)')
parser.add_argument('--top-k', type=int, default=2,
help='number of chunks to retrieve (default: 2)')
args = parser.parse_args()
answer = run_pipeline(args.file, args.question, args.chunk_size, args.overlap, args.top_k)
print('Answer:', answer)
if __name__ == '__main__':
main()This script uses argparse to define two positional arguments, file and question, and three optional arguments with defaults. The --chunk-size, --overlap, and --top-k options let the user override the defaults.
Run the Tool
Now you can run the tool from the command line. Make sure you have a plain-text file called sample.txt in the same directory. If you do not have one, create a small text file with a few sentences about retrieval-augmented generation. Then run:
python cli.py sample.txt "What is retrieval-augmented generation?"The tool will read the file, split it into chunks, retrieve the most relevant chunks, build a prompt, generate an answer with the placeholder model, and print the answer. The output will start with Answer: and then contain a sentence from the document that shares words with the question. The exact sentence depends on the content of your file and the placeholder model's score.
You can also try the optional arguments. For example, to use chunks of 20 words with an overlap of 5 and retrieve the top 3 chunks, run:
python cli.py sample.txt "What is retrieval-augmented generation?" --chunk-size 20 --overlap 5 --top-k 3The tool will use these values instead of the defaults. Experiment with different values to see how they affect the retrieved chunks and the final answer.
Handle Errors Gracefully
A good command-line tool gives clear error messages when something goes wrong. For example, if the user forgets to provide the file or question, argparse will automatically print a usage message and exit with an error. Try running:
python cli.pyYou will see a message like:
usage: cli.py [-h] [--chunk-size CHUNK_SIZE] [--overlap OVERLAP] [--top-k TOP_K] file question
cli.py: error: the following arguments are required: file, questionIf the file does not exist, Python will raise a FileNotFoundError. You can catch this error in cli.py and print a friendly message. Modify cli.py to add a shebang line at the top and catch the error. The final cli.py should look like this:
#!/usr/bin/env python3
import argparse
from pipeline import run_pipeline
def main():
parser = argparse.ArgumentParser(
description='Answer a question based on a document using retrieval-augmented generation.'
)
parser.add_argument('file', help='path to the plain-text document')
parser.add_argument('question', help='the question to answer')
parser.add_argument('--chunk-size', type=int, default=10,
help='number of words per chunk (default: 10)')
parser.add_argument('--overlap', type=int, default=5,
help='number of overlapping words between chunks (default: 5)')
parser.add_argument('--top-k', type=int, default=2,
help='number of chunks to retrieve (default: 2)')
args = parser.parse_args()
try:
answer = run_pipeline(args.file, args.question, args.chunk_size, args.overlap, args.top_k)
except FileNotFoundError:
print(f'Error: file not found: {args.file}')
return
print('Answer:', answer)
if __name__ == '__main__':
main()Now if you run the tool with a file that does not exist, you will see a clear error message instead of a traceback. For example:
python cli.py missing.txt "What is retrieval-augmented generation?"Error: file not found: missing.txtMake the Tool Executable
The shebang line at the top of cli.py tells the operating system which interpreter to use. On a Unix-like system (Linux or macOS), make the file executable with:
chmod +x cli.pyNow you can run the tool directly without typing python:
./cli.py sample.txt "What is retrieval-augmented generation?"On Windows, you can still run it with python cli.py. This step is optional but convenient if you use the tool often.
Key takeaways
- Use
argparseto build a command-line interface with positional and optional arguments. - Separate the pipeline logic into a function that returns the answer, so it can be reused and tested.
- Handle common errors like missing files with clear messages instead of tracebacks.
- A shebang line and executable permission let you run the script directly on Unix-like systems.
Try it
Write a new command-line tool called qa.py that uses the same pipeline but adds an option --instruction to specify a custom instruction for the prompt. Copy cli.py to qa.py and add the argument. Modify run_pipeline in pipeline.py to accept an instruction parameter with the default 'Answer the question based only on the following context.\n\n', and pass it to build_prompt. Then run qa.py with a document and a question using the default instruction, and again with a custom instruction like 'Use the context to answer. If unsure, say so.' Print the answer in both cases. A good result shows the tool works with both instructions and the answer may change if the custom instruction affects the placeholder model's behaviour.
Official documentation
Written with AI and checked automatically. Tools change, so a command may behave differently in the version you install. Spotted a mistake? Tell us.