# 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)

```bash
uv sync
```

Install extras as needed:

```bash
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)

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

## Running examples

Examples are available as importable modules under `ketju.examples`:

```bash
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:

```bash
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:

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

To see all logs again:

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

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

```bash
uv run python examples/basic_usage.py
```

## Development

### Tests

```bash
uv run pytest
```

With coverage (requires `pytest-cov`):

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

### Linting

```bash
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)
```
