RAG Engine

Hybrid search (keyword + semantic) + agentic multi-tool retrieval + cross-company/period comparison over SEC filings. Python, pgvector, uv.

Setup

git clone <repo> && cd rag
cp .env.example .env      # add GEMINI_API_KEY
docker compose up -d --wait
uv sync
uv run chunk

Use

uv run rag "query" rag
uv run agent "query"
uv run search hybrid "query"
uv run search compare "query" --tickers KO,PEP
uv run evaluation

## Stack

- LLM: Gemini (`GEMINI_API_KEY`)
- Embeddings: sentence-transformers
- DB: Postgres + pgvector, Docker
- Keyword search: Postgres full-text (tsvector)

## Quick wins
- change llm model

## Examples

### Hybrid search + citations

uv run search hybrid "coca cola revenue" --expand --summary --citations --rerank batch

Extracted filters: {'ticker': 'KO'} Expanded query: net operating revenues net sales total revenues revenue recognition

Answer: Coca-Cola's total net operating revenues were:

• $12,472 million for the three months ended April 3, 2026 [1].
• $11,129 million for the three months ended March 28, 2025 [1].

Net operating revenues are generated by selling sparkling soft drinks and other finished beverages to retailers, distributors, and wholesalers [2, 3]. Management considers the impact of acquisitions and divestitures when evaluating net operating revenue performance [4, 5]. Operating margin is calculated by dividing operating income by net operating revenues [6].

### Agentic search (picks its own tools, iterates until it has enough)

uv run agent "any cybersecurity incidents disclosed by KO"

Agentic search: "any cybersecurity incidents disclosed by KO" [1] hybrid_search('KO cybersecurity incidents') → 10 hit(s), 10 new unique | I will start with a hybrid search using the ticker and the specific topic to find relevant disclosures. [2] topic_search('cybersecurity') → 10 hit(s), 10 new unique | The initial hybrid search returned general sections; using the specialized cybersecurity topic tag will help isolate specific disclosures related to the user's request.Top 5 result(s): Based on the provided search results, there are no cybersecurity incidents disclosed by KO (Coca Cola Co) [3].

### Cross-company / cross-period comparison

uv run search compare "long-term debt" --tickers KO,PEP --start-period 2024

Comparison grid (3 cell(s)):

• KO (COCA COLA CO) — most recent, period ending 2026-04-03: 3 hit(s)
• KO (COCA COLA CO) — ~6 month(s) prior, period ending 2025-12-31: 3 hit(s)
• PEP (PepsiCo, Inc.) — most recent, period ending 2025-12-27: 3 hit(s)

Answer: The query focuses on long-term debt across KO (Coca-Cola Co) and PEP (PepsiCo, Inc.) for their most recent and prior periods. It is important to note that KO's fiscal year ends on December 31, while PepsiCo's fiscal year ends on the last Saturday in December (e.g., December 27, 2025), making their December 2025 data points roughly comparable [5, 7].

KO (COCA COLA CO) — most recent, period ending 2026-04-03: During the three months ended April 3, 2026, Coca-Cola made payments of long-term debt totaling $16 million [1]. For the three months ended March 28, 2025, the company had long-term debt issuances of $486 million, net of related discounts and issuance costs, and made payments of long-term debt of $552 million [1, 2]. Coca-Cola regularly assesses its optimal mix of short-term and long-term debt and maintains the ability to issue long-term debt [3].

KO (COCA COLA CO) — ~6 month(s) prior, period ending 2025-12-31: As of December 31, 2025, Coca-Cola's long-term debt, net of the current portion, was $42,119 million, a slight decrease from $42,375 million as of December 31, 2024 [5]. The total long-term debt before subtracting the current portion was $43,941 million as of December 31, 2025, compared to $43,023 million as of December 31, 2024 [5]. The current portion of long-term debt significantly increased to $1,822 million as of December 31, 2025, from $648 million as of December 31, 2024 [5]. Coca-Cola's long-term debt primarily consisted of fixed interest rate U.S. dollar notes, U.S. dollar debentures, Euro notes, and Swiss franc notes, with maturities extending through 2098 [5]. The company's expected maturities of long-term debt for the five years succeeding December 31, 2025, include $1,822 million in 2026, $4,817 million in 2027, $2,923 million in 2028, $2,955 million in 2029, and $3,411 million in 2030 [6]. Coca-Cola considers various alternatives for settling its long-term debt, such as cash flows from operating activities, commercial paper, or other long-term debt issuances [4].

PEP (PepsiCo, Inc.) — most recent, period ending 2025-12-27: PepsiCo's total long-term debt, net of current maturities, was $42,321 million as of 2025, marking an increase from $37,224 million as of 2024 [7]. The total long-term debt obligations before subtracting current maturities were $46,351 million as of 2025, up from $41,228 million as of 2024 [7]. The current maturities of long-term debt were $4,030 million as of 2025, a slight increase from $4,004 million as of 2024 [7]. PepsiCo's long-term debt includes notes due from 2025 to 2060 [7]. In 2025, PepsiCo reported proceeds from issuances of long-term debt of $8.2 billion and payments of long-term debt borrowings of $4.1 billion. In 2024, these figures were $4.0 billion in proceeds and $3.9 billion in payments [8].

Comparison:

Similarities:

• Overall Long-Term Debt Amounts (Late 2025): Both companies reported very similar total long-term debt, net of current portions, at their respective year-ends in late 2025. KO had $42,119 million as of December 31, 2025 [5], while PepsiCo had $42,321 million as of December 27, 2025 [7].
• Long-Term Maturity Profiles: Both companies have long-term debt obligations extending several decades into the future, with KO's notes due through 2098 and PepsiCo's through 2060 [5, 7].
• Strategic Management: Both companies actively manage their debt portfolios, with KO regularly reviewing its optimal mix of short-term and long-term debt [3], and PepsiCo engaging in significant issuance and payment activities [8].

Differences:

• Trend in Long-Term Debt (2024 to 2025): KO's long-term debt (net of current portion) slightly decreased from $42,375 million in 2024 to $42,119 million in 2025 [5]. In contrast, PepsiCo's long-term debt (net of current maturities) significantly increased from $37,224 million in 2024 to $42,321 million in 2025 [7].
• Issuances vs. Payments (Annual/Quarterly): For the three months ended April 3, 2026, KO's long-term debt payments were $16 million [1]. For the three months ended March 28, 2025, KO's long-term debt payments ($552 million) exceeded issuances ($486 million) [1, 2]. PepsiCo, however, had a net increase in long-term debt from financing activities in 2025, with proceeds from issuances ($8.2 billion) significantly exceeding payments ($4.1 billion) [8]. This indicates a more aggressive debt issuance strategy by PepsiCo in 2025 compared to KO's reported quarterly activities.
• Current Portion of Long-Term Debt: PepsiCo's current maturities of long-term debt were $4,030 million as of 2025 [7], which is more than double KO's current portion of $1,822 million as of December 31, 2025 [5]. This suggests PepsiCo has a larger proportion of its long-term debt maturing in the immediate upcoming year compared to KO.
• Detailed Maturity Schedule: KO provides a specific five-year maturity schedule for its long-term debt succeeding December 31, 2025 [6], which is not explicitly provided in the PepsiCo excerpts.