Metadata-Version: 2.4
Name: ketju
Version: 0.1.1
Summary: A Python library
Project-URL: Homepage, https://github.com/Novia-RDI-Seafaring/ketju
Project-URL: Repository, https://github.com/Novia-RDI-Seafaring/ketju
Project-URL: Issues, https://github.com/Novia-RDI-Seafaring/ketju/issues
Author-email: Christoffer Björkskog <christoffer.bjorkskog@novia.fi>
Maintainer: Novia UAS
License: MIT
License-File: LICENSE
Keywords: library,novia
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: devtools>=0.12.2
Requires-Dist: pydantic>=2.0.0
Provides-Extra: agent
Requires-Dist: pydantic-ai-slim[cli,openai]; extra == 'agent'
Provides-Extra: agui
Requires-Dist: llama-index-protocols-ag-ui>=0.2.3; extra == 'agui'
Requires-Dist: pydantic-ai-slim[ag-ui]; extra == 'agui'
Requires-Dist: starlette; extra == 'agui'
Requires-Dist: uvicorn; extra == 'agui'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docling
Requires-Dist: docling>=2.68.0; extra == 'docling'
Requires-Dist: langchain-docling>=2.0.0; extra == 'docling'
Requires-Dist: llama-index-node-parser-docling>=0.4.2; extra == 'docling'
Requires-Dist: llama-index-readers-docling>=0.4.2; extra == 'docling'
Provides-Extra: examples
Requires-Dist: chromadb; extra == 'examples'
Requires-Dist: docling>=2.68.0; extra == 'examples'
Requires-Dist: langchain-docling>=2.0.0; extra == 'examples'
Requires-Dist: llama-index-embeddings-ollama>=0.8.6; extra == 'examples'
Requires-Dist: llama-index-llms-litellm>=0.6.3; extra == 'examples'
Requires-Dist: llama-index-node-parser-docling>=0.4.2; extra == 'examples'
Requires-Dist: llama-index-observability-otel>=0.2.1; extra == 'examples'
Requires-Dist: llama-index-protocols-ag-ui>=0.2.3; extra == 'examples'
Requires-Dist: llama-index-readers-docling>=0.4.2; extra == 'examples'
Requires-Dist: llama-index-vector-stores-chroma>=0.5.5; extra == 'examples'
Requires-Dist: llama-index>=0.14.12; extra == 'examples'
Requires-Dist: logfire>=4.10.0; extra == 'examples'
Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.51.1; extra == 'examples'
Requires-Dist: pydantic-ai-slim[ag-ui,cli,openai]; extra == 'examples'
Requires-Dist: pypdf>=6.6.0; extra == 'examples'
Requires-Dist: pysrt>=1.1.2; extra == 'examples'
Requires-Dist: pysword>=0.2.8; extra == 'examples'
Requires-Dist: python-dotenv; extra == 'examples'
Requires-Dist: starlette; extra == 'examples'
Requires-Dist: uvicorn; extra == 'examples'
Provides-Extra: observability
Requires-Dist: llama-index-observability-otel>=0.2.1; extra == 'observability'
Requires-Dist: logfire>=4.10.0; extra == 'observability'
Requires-Dist: opentelemetry-exporter-otlp; extra == 'observability'
Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.51.1; extra == 'observability'
Requires-Dist: opentelemetry-sdk; extra == 'observability'
Provides-Extra: pgvector
Requires-Dist: llama-index-storage-docstore-postgres>=0.4.1; extra == 'pgvector'
Requires-Dist: llama-index-storage-index-store-postgres>=0.5.1; extra == 'pgvector'
Requires-Dist: llama-index-storage-kvstore-postgres>=0.4.3; extra == 'pgvector'
Requires-Dist: llama-index-vector-stores-postgres>=0.7.3; extra == 'pgvector'
Provides-Extra: rag
Requires-Dist: chromadb; extra == 'rag'
Requires-Dist: llama-index-embeddings-ollama>=0.8.6; extra == 'rag'
Requires-Dist: llama-index-llms-litellm>=0.6.3; extra == 'rag'
Requires-Dist: llama-index-vector-stores-chroma>=0.5.5; extra == 'rag'
Requires-Dist: llama-index>=0.14.12; extra == 'rag'
Requires-Dist: pypdf>=6.6.0; extra == 'rag'
Requires-Dist: pysrt>=1.1.2; extra == 'rag'
Requires-Dist: pysword>=0.2.8; extra == 'rag'
Description-Content-Type: text/markdown

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