Metadata-Version: 2.4
Name: eyecore
Version: 1.0.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: requests>=2.28 ; extra == 'corpus'
Requires-Dist: feedparser>=6.0 ; extra == 'feed'
Requires-Dist: requests>=2.28 ; extra == 'feed'
Requires-Dist: beautifulsoup4>=4.12 ; extra == 'feed'
Requires-Dist: ollama>=0.1 ; extra == 'llm'
Requires-Dist: openai>=1.0 ; extra == 'llm'
Requires-Dist: llama-cpp-python>=0.2 ; extra == 'llm'
Requires-Dist: llama-cpp-python>=0.2 ; extra == 'llm-cpp'
Requires-Dist: ollama>=0.1 ; extra == 'llm-ollama'
Requires-Dist: openai>=1.0 ; extra == 'llm-openai'
Requires-Dist: pytest>=7.0 ; extra == 'test'
Requires-Dist: pytest-cov>=4.0 ; extra == 'test'
Provides-Extra: corpus
Provides-Extra: feed
Provides-Extra: llm
Provides-Extra: llm-cpp
Provides-Extra: llm-ollama
Provides-Extra: llm-openai
Provides-Extra: test
License-File: LICENSE
Summary: Core data retrieval and organisation library — SQLite DB, topic graph, corpus management, and LLM integration
Keywords: database,knowledge-graph,corpus,llm
Author-email: Andrew Watts <andrewkwatts@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/andrewkwatts-maker/EyeCore
Project-URL: Issues, https://github.com/andrewkwatts-maker/EyeCore/issues
Project-URL: Repository, https://github.com/andrewkwatts-maker/EyeCore

# eyecore

Core data retrieval and organisation library — SQLite DB management, topic graph, corpus management, and LLM integration.

## Features

- **BaseDB** — lazy SQLite connection with transparent `.db.gz` decompression to user cache
- **TopicGraph** — generalized topic registry with parent/child relationships, BFS traversal, and typed links
- **CorpusManager** — on-demand corpus checkout (Project Gutenberg, URL, git) with FTS5 indexing
- **LLMClient** — lazy-loaded LLM wrapper with auto-detected backends (Ollama, llama-cpp, OpenAI-compatible)
- **compress_db / decompress_to_cache** — platform-aware compression utilities for bake scripts

## Installation

```bash
pip install eyecore
```

With optional extras:

```bash
pip install "eyecore[llm-ollama]"   # Ollama backend
pip install "eyecore[llm-cpp]"      # llama-cpp-python backend
pip install "eyecore[llm-openai]"   # OpenAI-compatible backend
pip install "eyecore[corpus]"       # corpus download support
```

## Quick start

```python
from pathlib import Path
from eyecore import BaseDB, TopicGraph, CorpusManager, LLMClient

# Lazy SQLite — decompresses .db.gz to user cache on first access
db = BaseDB("myapp", gz_path=Path("data/myapp.db.gz"))
rows = db.fetchall("SELECT * FROM entities LIMIT 10")

# Topic graph
graph = TopicGraph(db.conn)
related = graph.get_related("topic-id")
tree    = graph.subtree("root-id")

# LLM — auto-detects Ollama / llama-cpp / OpenAI
llm = LLMClient.get()
if llm.is_available():
    summary = llm.summarize("Some long text to summarize...")
    topics  = llm.extract_topics("Article text about AI and machine learning...")
    report  = llm.generate_report(articles, "Technology", "title", "summary")
```

## LLM configuration

Configure via environment variables:

| Variable | Default | Description |
|---|---|---|
| `LLM_BACKEND` | auto | `ollama`, `llama-cpp`, or `openai` |
| `LLM_MODEL` | `llama3` | Model name (Ollama) or model ID (OpenAI) |
| `LLM_HOST` | `http://localhost:11434` | Ollama server URL |
| `LLM_MODEL_PATH` | — | Path to GGUF model file (llama-cpp) |
| `OPENAI_API_KEY` | — | API key for OpenAI-compatible endpoints |
| `OPENAI_BASE_URL` | — | Base URL for OpenAI-compatible endpoints |


## License

MIT — see [LICENSE](LICENSE)

