utils/retrieving_utils.cpp
| Line | Branch | Exec | Source |
|---|---|---|---|
| 1 | #include "retrieving_utils.hpp" | ||
| 2 | #include <nlohmann/json.hpp> | ||
| 3 | #include <string> | ||
| 4 | #include <vector> | ||
| 5 | |||
| 6 | using nlohmann::json_abi_v3_11_2::json; | ||
| 7 | |||
| 8 | /** | ||
| 9 | * Constructs a RetrievingUtils instance with the configuration and collaborators it needs to retrieve stored | ||
| 10 | * embeddings. | ||
| 11 | * | ||
| 12 | * @param config: Shared pointer to the RetrievingUtilsConfig that supplies the retrieval settings. | ||
| 13 | * @param ui: Shared pointer to the UserInterface used to display messages and status. | ||
| 14 | * @param curl: Shared pointer to the CurlUtils used to perform HTTP requests. | ||
| 15 | * @param ollama_client: Shared pointer to the OllamaClient used to generate query embeddings. | ||
| 16 | * @param storage_client: Shared pointer to the QdrantClient used to search stored embeddings. | ||
| 17 | * | ||
| 18 | * Initializes the config, ui, curl, ollama_client, and storage_client members by copying each shared pointer, so this | ||
| 19 | * instance shares ownership of every dependency with the caller. The constructor body is empty, so no other work is | ||
| 20 | * performed. | ||
| 21 | * | ||
| 22 | * Note: Because the dependencies are shared, they remain alive as long as any holder still references them. Passing a | ||
| 23 | * null pointer is not checked here, so any later use of a null dependency will fail at the point of use. | ||
| 24 | */ | ||
| 25 | ✗ | RetrievingUtils::RetrievingUtils(std::shared_ptr<RetrievingUtilsConfig> config, std::shared_ptr<UserInterface> ui, | |
| 26 | std::shared_ptr<CurlUtils> curl, std::shared_ptr<OllamaClient> ollama_client, | ||
| 27 | ✗ | std::shared_ptr<QdrantClient> storage_client) | |
| 28 | ✗ | : config(config), ui(ui), curl(curl), ollama_client(ollama_client), storage_client(storage_client) { | |
| 29 | ✗ | } | |
| 30 | |||
| 31 | /** | ||
| 32 | * Retrieves the stored document chunks that are most similar to a user question. | ||
| 33 | * | ||
| 34 | * @param question: The natural-language question to search for. | ||
| 35 | * @return The text payloads of the top matching chunks from Qdrant, ordered by similarity. The list has at most | ||
| 36 | * config->k entries. | ||
| 37 | * @throws std::runtime_error If the "embedding_model" config property or the "embed_url" or "collections_url" URL | ||
| 38 | * property is not supported, or if the "embedding_model" value is not a std::string. | ||
| 39 | * @throws nlohmann::json::parse_error If the embedding response or the search response is not valid JSON. | ||
| 40 | * @throws nlohmann::json::type_error If the embedding response does not contain a numeric "embeddings" array, or if a | ||
| 41 | * search result does not contain a string "payload" "text" field. | ||
| 42 | * | ||
| 43 | * Builds a JSON request with the embedding model name and the question, then posts it to the Ollama embed URL through | ||
| 44 | * the CurlUtils instance. The first vector in the returned "embeddings" array becomes the question embedding. That | ||
| 45 | * vector, the configured result limit k, and a flag requesting payloads are serialized into a search request. The | ||
| 46 | * request is posted to the "rag-app/points/search" endpoint under the Qdrant collections URL, with the api-key header | ||
| 47 | * set from the QDRANT_API_KEY environment variable. Each entry in the "result" array of the search response contributes | ||
| 48 | * its payload text to the returned list. In debug builds, when the UI is not running, both raw responses are printed | ||
| 49 | * to the non-interactive output. | ||
| 50 | * | ||
| 51 | * Note: The method depends on the QDRANT_API_KEY environment variable. If it is unset, the null pointer passed to the | ||
| 52 | * header map is not checked, which can cause undefined behavior or a std::logic_error at construction. The response | ||
| 53 | * is not checked for HTTP errors before parsing, so an error body from either service typically surfaces as a parse or | ||
| 54 | * type exception. The method reads only the first embedding, so it expects the embed service to return exactly one | ||
| 55 | * vector for the single question. | ||
| 56 | */ | ||
| 57 | ✗ | std::vector<std::string> RetrievingUtils::retrieve(const std::string& question) { | |
| 58 | ✗ | json request_payload = {{"model", this->ollama_client->get_config_value<std::string>("embedding_model")}, | |
| 59 | ✗ | {"input", question}}; | |
| 60 | |||
| 61 | ✗ | std::string post_data = request_payload.dump(); | |
| 62 | |||
| 63 | ✗ | std::string response = this->curl->fetch_web_content(this->ollama_client->get_url_value("embed_url"), post_data); | |
| 64 | |||
| 65 | #ifdef DEBUG | ||
| 66 | ✗ | if (this->ui->backend_running() == false) { | |
| 67 | ✗ | UserInterface::print_message_noninteractive(std::format("\t[DEBUG] question embed response {}\n", response)); | |
| 68 | } | ||
| 69 | #endif | ||
| 70 | |||
| 71 | ✗ | json data = json::parse(response); | |
| 72 | |||
| 73 | ✗ | std::vector<float> question_embedding = data["embeddings"][0].get<std::vector<float>>(); | |
| 74 | |||
| 75 | ✗ | request_payload = {{"vector", question_embedding}, {"limit", this->config->k}, {"with_payload", true}}; | |
| 76 | |||
| 77 | ✗ | post_data = request_payload.dump(); | |
| 78 | |||
| 79 | std::string url = | ||
| 80 | ✗ | std::format("{}/{}", this->storage_client->get_url_value("collections_url"), "rag-app/points/search"); | |
| 81 | |||
| 82 | ✗ | const char* qdrant_key = std::getenv("QDRANT_API_KEY"); | |
| 83 | ✗ | std::map<std::string, std::string> headers{{"api-key", qdrant_key}}; | |
| 84 | |||
| 85 | ✗ | response = this->curl->fetch_web_content(url, post_data, "POST", headers); | |
| 86 | |||
| 87 | #ifdef DEBUG | ||
| 88 | ✗ | if (this->ui->backend_running() == false) { | |
| 89 | ✗ | UserInterface::print_message_noninteractive(std::format("\t[DEBUG] search response {}\n", response)); | |
| 90 | } | ||
| 91 | #endif | ||
| 92 | |||
| 93 | ✗ | data = json::parse(response); | |
| 94 | |||
| 95 | ✗ | std::vector<std::string> documents; | |
| 96 | |||
| 97 | ✗ | std::transform(data["result"].begin(), data["result"].end(), std::back_inserter(documents), | |
| 98 | ✗ | [](const auto& result) { return result["payload"]["text"].template get<std::string>(); }); | |
| 99 | |||
| 100 | ✗ | return documents; | |
| 101 | ✗ | } | |
| 102 | |||
| 103 | /** | ||
| 104 | * Builds a retrieval-augmented prompt from a question and its supporting documents, sends it to the Ollama generate | ||
| 105 | * endpoint, and processes the model's answer. | ||
| 106 | * | ||
| 107 | * @param question: The user question that the model should answer. | ||
| 108 | * @param documents: The retrieved document texts that provide context for the answer. Each entry is joined with a | ||
| 109 | * newline. | ||
| 110 | * @throws std::runtime_error If the "model" or "stream" config property is not supported or has an unexpected type, or | ||
| 111 | * if the "generate_url" URL property is not supported. | ||
| 112 | * @throws nlohmann::json::exception If the streamed or non-streamed response cannot be parsed, as propagated from the | ||
| 113 | * OllamaClient response handlers. | ||
| 114 | * | ||
| 115 | * Concatenates the document texts into one string, separating entries with newlines, and places that string together | ||
| 116 | * with the question into a fixed instruction template. The template asks the model to answer in at most three | ||
| 117 | * sentences and to say when it does not know the answer. The prompt, the model name, a temperature of 0, and the | ||
| 118 | * stream flag are serialized into a JSON request. When streaming is enabled, the request is posted through | ||
| 119 | * fetch_web_content_stream, and each received chunk is forwarded to OllamaClient::process_response_stream. The | ||
| 120 | * resulting success flag and status are then reported through the UI or the non-interactive output. When streaming is | ||
| 121 | * disabled, the request is posted with fetch_web_content, and the full body is passed to | ||
| 122 | * OllamaClient::process_response. | ||
| 123 | * | ||
| 124 | * Note: The question and document text are inserted into the prompt without escaping or sanitizing, so instructions | ||
| 125 | * contained in retrieved documents can influence the model. The method does not check whether the documents vector is | ||
| 126 | * empty, although the join loop itself handles that case safely. Errors from the HTTP layer are not inspected beyond | ||
| 127 | * the stream status message, so a failed non-streamed request reaches the response handler as-is. | ||
| 128 | */ | ||
| 129 | ✗ | void RetrievingUtils::generate_answer(const std::string& question, const std::vector<std::string>& documents) { | |
| 130 | ✗ | std::string document_texts{}; | |
| 131 | |||
| 132 | ✗ | for (size_t i = 0; i < documents.size(); i += 1) { | |
| 133 | ✗ | document_texts += documents[i]; | |
| 134 | ✗ | if (i < documents.size() - 1) document_texts += "\n"; | |
| 135 | } | ||
| 136 | |||
| 137 | std::string prompt = R"(You are an assistant for question-answering tasks. | ||
| 138 | Use the following documents to answer the question. | ||
| 139 | If you don't know the answer, just say that you don't know. | ||
| 140 | Use three sentences maximum and keep the answer concise: | ||
| 141 | ✗ | Question: )" + question + R"( | |
| 142 | ✗ | Documents: )" + document_texts | |
| 143 | ✗ | + R"( | |
| 144 | Answer: | ||
| 145 | )"; | ||
| 146 | |||
| 147 | ✗ | json request_payload = {{"model", this->ollama_client->get_config_value<std::string>("model")}, | |
| 148 | {"prompt", prompt}, | ||
| 149 | ✗ | {"temperature", 0}, | |
| 150 | ✗ | {"stream", this->ollama_client->get_config_value<bool>("stream")}}; | |
| 151 | |||
| 152 | ✗ | std::string post_data = request_payload.dump(); | |
| 153 | |||
| 154 | ✗ | if (this->ollama_client->get_config_value<bool>("stream")) { | |
| 155 | ✗ | WebContentStream response = this->curl->fetch_web_content_stream( | |
| 156 | ✗ | this->ollama_client->get_url_value("generate_url"), post_data, | |
| 157 | ✗ | [this](const std::string& chunk) { this->ollama_client->process_response_stream(chunk); }); | |
| 158 | ✗ | std::string message = std::format("Stream successful: {}, Status: {}\n", response.success, response.status); | |
| 159 | ✗ | if (this->ui->backend_running() == false) { | |
| 160 | ✗ | UserInterface::print_message_noninteractive(message); | |
| 161 | } else { | ||
| 162 | ✗ | this->ui->print_message(message); | |
| 163 | } | ||
| 164 | ✗ | } else { | |
| 165 | std::string response = | ||
| 166 | ✗ | this->curl->fetch_web_content(this->ollama_client->get_url_value("generate_url"), post_data); | |
| 167 | ✗ | this->ollama_client->process_response(response); | |
| 168 | ✗ | } | |
| 169 | ✗ | } | |
| 170 | |||
| 171 | /** | ||
| 172 | * Runs one retrieval-augmented question-answering cycle using the prompt from the configuration. | ||
| 173 | * | ||
| 174 | * @throws std::runtime_error If the "prompt" config property is not supported or has an unexpected type, or if | ||
| 175 | * retrieve or generate_answer fails with a runtime error. | ||
| 176 | * @throws nlohmann::json::parse_error If a retrieval response cannot be parsed as JSON, as propagated from retrieve. | ||
| 177 | * @throws nlohmann::json::type_error If a retrieval response has an unexpected JSON structure, as propagated from | ||
| 178 | * retrieve. | ||
| 179 | * | ||
| 180 | * Reads the "prompt" string from the Ollama client configuration and keeps a constant reference to it. The prompt is | ||
| 181 | * then shown to the user as a message, either through the interactive UI when it is running or through non-interactive | ||
| 182 | * output otherwise. The same prompt is used as the search input for retrieve, which embeds it and returns the matching | ||
| 183 | * document texts from the vector store. Those documents, together with the prompt as the question, are passed to | ||
| 184 | * generate_answer, which builds the final prompt, queries the model, and processes the answer. | ||
| 185 | * | ||
| 186 | * Note: The prompt is both the displayed user message and the retrieval query, and it is also used as the question in | ||
| 187 | * generate_answer. Because the returned reference points into the configuration object, the configuration must outlive | ||
| 188 | * this method. The method performs no check on whether retrieve returned any documents, so generate_answer is called | ||
| 189 | * even with an empty list. | ||
| 190 | */ | ||
| 191 | ✗ | void RetrievingUtils::run() { | |
| 192 | ✗ | const std::string& prompt = this->ollama_client->get_config_value<std::string>("prompt"); | |
| 193 | |||
| 194 | ✗ | std::string message = std::format("💬 user: {}\n", prompt); | |
| 195 | ✗ | if (this->ui->backend_running() == false) { | |
| 196 | ✗ | UserInterface::print_message_noninteractive(message); | |
| 197 | } else { | ||
| 198 | ✗ | this->ui->print_message(message); | |
| 199 | } | ||
| 200 | |||
| 201 | ✗ | auto documents = this->retrieve(prompt); | |
| 202 | |||
| 203 | ✗ | this->generate_answer(prompt, documents); | |
| 204 | ✗ | } | |
| 205 |