Metadata-Version: 2.4
Name: sigil-sdk-llamaindex
Version: 0.2.0
Summary: LlamaIndex callback handlers for Sigil Python SDK
License: SPDX-License-Identifier: Apache-2.0
        
        See /LICENSE at repository root for full license text.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sigil-sdk>=0.2.0
Requires-Dist: llama-index>=0.14.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Dynamic: license-file

# Sigil Python Framework Module: LlamaIndex

`sigil-sdk-llamaindex` provides callback handlers that map LlamaIndex workflow/agent events into Sigil generation recorder lifecycles.

## Installation

```bash
pip install sigil-sdk sigil-sdk-llamaindex
pip install llama-index
```

## Quickstart

```python
from sigil_sdk import Client
from sigil_sdk_llamaindex import with_sigil_llamaindex_callbacks

client = Client()
config = with_sigil_llamaindex_callbacks(None, client=client, provider_resolver="auto")
# query_engine = index.as_query_engine(callback_manager=config["callback_manager"])
```

## Native callback manager wiring

```python
from sigil_sdk import Client
from sigil_sdk_llamaindex import with_sigil_llamaindex_callbacks

client = Client()
config = with_sigil_llamaindex_callbacks(None, client=client, provider_resolver="auto")
# query_engine = index.as_query_engine(callback_manager=config["callback_manager"])
```

## Conversation mapping

Conversation ID precedence:

1. `conversation_id` / `session_id` / `group_id`
2. `thread_id`
3. fallback `sigil:framework:llamaindex:<run_id>`

## Metadata and lineage

- Required: `sigil.framework.run_type`
- Optional lineage: `sigil.framework.run_id`, `sigil.framework.thread_id`, `sigil.framework.parent_run_id`, `sigil.framework.component_name`, `sigil.framework.retry_attempt`, `sigil.framework.event_id`

## Provider resolver

Model prefix inference:

- `gpt-`/`o1`/`o3`/`o4` -> `openai`
- `claude-` -> `anthropic`
- `gemini-` -> `gemini`
- fallback `custom`

## Troubleshooting

- Reuse stable workflow/session IDs to keep conversation grouping stable.
- Keep `capture_inputs`/`capture_outputs` enabled while validating mappings.
- Call `client.flush()` at checkpoints and `client.shutdown()` on exit.
