Ketju

Ketju is a small RAG-focused codebase for experimenting with document ingestion and question answering. Its goal is to be a lightweight RAG engine enabling rapid prototyping, experimentation, and iteration.

Installation

Using uv (recommended)

uv sync

Install extras as needed:

uv sync --extra rag
uv sync --extra pgvector
uv sync --extra docling
uv sync --extra agent
uv sync --extra agui
uv sync --extra observability
uv sync --extra examples
uv sync --extra dev

Examples

Chat with pdf's

paste in file paths you paths in the conversation. Launch via.

uv run python -m ketju.examples.basic_usage

Chat with docs using pgvector

➜  ketju git:(main) uv run python -m ketju.examples.pgvector_example --database-url "postgresql://postgres:admin123@127.0.0.1:5432/ketju_db"

Starting the agent...

You can ask questions about contents in pdf files, just paste the path to the file in the chat.

ketju-agent ➤ compare the time travel properties of docs/interdimensional-systems/Infini
te_Improbability_Drive_Technical_Manual.pdf and docs/interdimensional-systems/Flux_Capac
itor_Technical_Reference_Manual.pdf present tehcnical specs in a table

Below is a comparative table of the time travel properties and technical specifications 
of the Infinite Improbability Drive and the Flux Capacitor:                             

                                                                                        
                           Infinite Improbability Drive                                 
  Specification            (IID)                          Flux Capacitor                
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 
  Functionality            Probabilistic                  Temporal Displacement         
                           Faster-Than-Light Propulsion                                 
  Transit Duration         0.8 to 1.3 seconds (nominal    Temporal energy delivery      
                           1.0 second)                    within 2.3 milliseconds       
  Improbability Index      10^6:1 to 10^24:1              N/A                           
  Quantum Field Density    4.2e9 to 9.5e9 J/m³            Chroniton Flux Density:       
                                                          3.6e12 particles/cm³          
  Reality Phase Variance   0.002 to 0.0005 Δφ             N/A                           
  Causality Drift          ±0.05 to ±1.2 milliseconds     N/A                           
  Power Requirements       Peak: 2.8e15 Joules;           Nominal Input: 1.21           
                           Sustained: 3.5e12 Watts        Gigawatts                     
  Cooling Medium           N/A                            Liquid Nitrogen               
  Weight                   N/A                            15.4 kg                       
  Housing Material         N/A                            Reinforced Titanium Alloy     
  Dimensions               N/A                            450 x 320 x 150 mm            
  Warnings                 Risk of uncontrolled           Improper synchronization can  
                           metaphysical side effects      lead to spacetime shear       
                                                          events or disintegration      
  Primary Risk Vector      Reality Instability            Causality Disruption          
                                                                                        

### Key Observations:

 • The IID operates based on improbability levels and focuses on navigation through     
   controlled quantum fields, while the Flux Capacitor is centered around achieving time
   travel via temporal displacement.                                                    
 • The IID does not provide precise time travel capabilities, whereas the Flux Capacitor
   requires a specific speed and energy input to achieve temporal displacement with high
   accuracy.                                                                            
 • The IID emphasizes energy at a much higher scale compared to the Flux Capacitor,     
   which requires relatively lower energy for its operations.                           

Let me know if you need any more information or additional comparisons!                 
ketju-agent ➤

AG-UI

Start backend

uv run python -m ketju.examples.agui_agent

or

uv run python -m ketju.examples.agui_agent --path=a/path/to/a/folder/or/pdf/file

and then start the frontend

cd ui
pnpm install
next dev

Using pip (fallback)

pip install -e .
pip install -e '.[rag]'

Running examples

Examples are available as importable modules under ketju.examples:

uv run python -m ketju.examples.basic_usage
uv run python -m ketju.examples.rag_comparison
uv run python -m ketju.examples.agui
uv run python -m ketju.examples.pgvector_example --database-url "postgresql://postgres:password@127.0.0.1:5432/ketju_db"

An instrumentation demo that prints spans to the console:

uv sync --extra rag --extra observability
uv run python -m ketju.examples.instrumentation_demo

To reduce noisy third-party logs while using the interactive CLI:

uv run python -m ketju.examples.basic_usage --log-level WARNING

To see all logs again:

uv run python -m ketju.examples.basic_usage --no-quiet

The top-level examples/ scripts remain as thin wrappers for convenience:

uv run python examples/basic_usage.py

Development

Tests

uv run pytest

With coverage (requires pytest-cov):

pytest --cov=ketju --cov-report=term-missing

Linting

uv run ruff check src tests

Project layout

ketju/
├── src/ketju/               # library code
├── tests/                   # unit tests (no optional deps required)
├── examples/                # wrapper scripts + docs
└── pyproject.toml           # metadata + dependency groups (extras)