Repository Public
1#!/usr/bin/env python32# =============================================================================3# SP BOUCHER | SOFTWARE & RESEARCH4# ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING5# =============================================================================6#7# PROJECT METADATA8# -----------------------------------------------------------------------------9# Project : API Atlas10# File : examples/gemini/file-search/file_search_lifecycle.py11# Description : File Search lifecycle (REST): create store → resumable12# uploadToFileSearchStore → poll operation → list/get13# documents → generateContent with the fileSearch tool (+14# metadataFilter) → delete document (?force=true) → delete15# store (?force=true).16# Module : examples17# Repository : https://git.spboucher.ai/doc-api18# Created : 2026-09-1919# Last Modified : 2026-09-1920#21# =============================================================================22# AUTHOR & PROFESSIONAL AFFILIATION23# =============================================================================24#25# Author : Simon-Pierre Boucher26# Position : Professor of Finance27# Institution : Université du Québec en Outaouais (UQO)28# Department : Département des sciences administratives29# Organization : SP Boucher30#31# Website : https://spboucher.ai32# Git : https://git.spboucher.ai33#34# =============================================================================35# OFFICIAL CONTACT DIRECTORY36# =============================================================================37#38# General : info@spboucher.ai39# Professional : contact@spboucher.ai40# Direct : simon@spboucher.ai41# Research : research@spboucher.ai42# Development : dev@spboucher.ai43# Support : support@spboucher.ai44# Security/Admin : admin@spboucher.ai45# Notifications : notifications@spboucher.ai46#47# Preferred Contact: contact@spboucher.ai48#49# =============================================================================50# COPYRIGHT & INTELLECTUAL PROPERTY51# =============================================================================52#53# Copyright (c) 202654# Simon-Pierre Boucher55#56# All rights reserved where applicable.57#58# This file is governed by the applicable project license,59# copyright notices, institutional agreements and relevant law.60#61# Unless expressly authorized by the applicable license or62# rights holder, copying, redistribution, sublicensing,63# publication and commercial exploitation are not permitted.64#65# Existing third-party rights and notices remain unaffected.66#67# =============================================================================68# CONFIDENTIALITY & SECURITY69# =============================================================================70#71# Classification : Public72# Distribution : Public repository; use is governed by the project license73# Security Contact : admin@spboucher.ai74#75# Access to this source does not independently grant permission76# to redistribute or disclose confidential materials.77#78# Do not embed credentials, private keys, access tokens,79# certificates or confidential personal information.80#81# =============================================================================82# LICENSE & MAINTENANCE83# =============================================================================84#85# License : None specified (no license file in this repository)86# Maintainer : Simon-Pierre Boucher87# Technical Contact: dev@spboucher.ai88#89# =============================================================================90# END OF SP BOUCHER SOURCE HEADER91# =============================================================================9293"""File Search lifecycle (REST): create store → resumable uploadToFileSearchStore → poll operation → list/get documents →94generateContent with the fileSearch tool (+ metadataFilter) → delete document (?force=true) → delete store (?force=true).95STATUS: LIVE_VERIFIED 2026-09-18 (tmp-live/gemini-tools/g*.json, gemini-3.5-flash-lite, indexing ≈ 50 tokens → < $0.001).96Observed: store {name, displayName, createTime, updateTime, embeddingModel: models/gemini-embedding-001, activeDocumentsCount, sizeBytes};97upload start → 200 + X-Goog-Upload-URL header; finalize → Operation {name, response} (done omitted until polled);98done operation.response {@type, documentName, mimeType, parent, sizeBytes}; document state STATE_ACTIVE; the fileSearch answer had99NO groundingMetadata on the candidate (only usageMetadata.toolUsePromptTokenCount 985); DELETE document without force → 400100FAILED_PRECONDITION "Cannot delete non-empty Document".101Run: .venv/bin/python examples/gemini/file-search/file_search_lifecycle.py102"""103import json, sys, time104from pathlib import Path105sys.path.insert(0, str(Path(__file__).resolve().parents[3]))106from scripts.live import GEMINI_BASE, gemini_request107MODEL = "gemini-3.5-flash-lite"108TEXT = b"The Atlas probe document. The secret fruit is kumquat. The secret number is 4711."109110st, store, _ = gemini_request("POST", "/v1beta/fileSearchStores", {"displayName": "atlas-example"}, note="file_search_lifecycle.py create store")111name = store["name"]; print("store:", st, name)112st, _, h = gemini_request("POST", f"/upload/v1beta/{name}:uploadToFileSearchStore",113 {"displayName": "probe.txt", "customMetadata": [{"key": "kind", "stringValue": "probe"}],114 "chunkingConfig": {"whiteSpaceConfig": {"maxTokensPerChunk": 200, "maxOverlapTokens": 20}}},115 extra_headers={"X-Goog-Upload-Protocol": "resumable", "X-Goog-Upload-Command": "start",116 "X-Goog-Upload-Header-Content-Length": str(len(TEXT)), "X-Goog-Upload-Header-Content-Type": "text/plain"},117 note="file_search_lifecycle.py upload start")118upload_url = next(v for k, v in h.items() if k.lower() == "x-goog-upload-url")119st, op, _ = gemini_request("POST", upload_url.replace(GEMINI_BASE, ""), data=TEXT, content_type="text/plain",120 extra_headers={"X-Goog-Upload-Offset": "0", "X-Goog-Upload-Command": "upload, finalize"}, note="file_search_lifecycle.py upload finalize")121print("operation:", st, op.get("name"), "done:", op.get("done"))122while not op.get("done"):123 time.sleep(2); st, op, _ = gemini_request("GET", f"/v1beta/{op['name']}", note="file_search_lifecycle.py poll")124doc = op["response"]["documentName"]; print("document:", doc)125st, docs, _ = gemini_request("GET", f"/v1beta/{name}/documents", note="file_search_lifecycle.py list documents")126print("documents:", [(d["displayName"], d["state"], d["sizeBytes"]) for d in docs.get("documents", [])])127st, r, _ = gemini_request("POST", f"/v1beta/models/{MODEL}:generateContent",128 {"contents": [{"parts": [{"text": "What is the secret fruit and the secret number? 6 words."}]}],129 "tools": [{"fileSearch": {"fileSearchStoreNames": [name], "metadataFilter": "kind=probe"}}], "generationConfig": {"maxOutputTokens": 48}},130 note="file_search_lifecycle.py fileSearch query")131cand = r["candidates"][0]132print("answer:", "".join(p.get("text", "") for p in cand["content"]["parts"]), "| groundingMetadata:", json.dumps(cand.get("groundingMetadata"))[:300],133 "| toolUsePromptTokenCount:", r["usageMetadata"].get("toolUsePromptTokenCount"))134st, _, _ = gemini_request("DELETE", f"/v1beta/{doc}?force=true", note="file_search_lifecycle.py delete document")135print("delete document:", st)136st, _, _ = gemini_request("DELETE", f"/v1beta/{name}?force=true", note="file_search_lifecycle.py delete store")137print("delete store:", st)138