Metadata-Version: 2.4
Name: littlehive
Version: 0.5.0
Summary: LittleHive local-first multi-agent assistant foundation
Author: LittleHive
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.6
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: alembic>=1.13
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: tenacity>=8.2
Requires-Dist: structlog>=24.1
Requires-Dist: PyYAML>=6.0
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: ui
Requires-Dist: nicegui>=2.0; extra == "ui"
Provides-Extra: groq
Requires-Dist: groq>=0.11; extra == "groq"
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Provides-Extra: full
Requires-Dist: python-telegram-bot>=21.0; extra == "full"
Requires-Dist: nicegui>=2.0; extra == "full"
Requires-Dist: groq>=0.11; extra == "full"

# LittleHive

LittleHive is a local-first, multi-model, multi-agent assistant platform optimized for small local models, strict context budgets, and low operating cost.

## Core Concepts
- ITR (Instruction-Tool Retrieval): only inject compact tool docs until invocation time.
- Memory Cards: typed compact reusable memory units, not full transcript replay.
- Transfer Primitive: clean-state handoffs between agents.
- Context Compiler: central token-budget preflight + deterministic trimming.

## Install
```bash
pip install littlehive
pip install "littlehive[telegram]"
pip install "littlehive[ui]"
pip install "littlehive[full]"
```

For development:
```bash
pip install -e ".[dev,telegram,ui]"
```

## Quickstart
1. Initialize config/env:
```bash
littlehive-onboard
```
2. Validate config/hardware/providers:
```bash
littlehive-diag --validate-config --hardware --check-providers
```
3. Start Telegram worker:
```bash
littlehive-telegram --config config/instance.yaml
```
4. Start admin API:
```bash
littlehive-api --config config/instance.yaml --host 127.0.0.1 --port 8080
```
5. Start Python dashboard (NiceGUI):
```bash
littlehive-dashboard --config config/instance.yaml --host 127.0.0.1 --port 8666
```

## Dashboard
`littlehive-dashboard` is Python-only (NiceGUI), no Node/React install required.

Main views:
- Overview
- Providers (health + breaker + routing score)
- Tasks/Traces
- Memory search
- Permissions and power controls
- Usage/Budgets
- Diagnostics/Failures
- Pending confirmations

## Safety and Permission Profiles
Supported permission profiles:
- `read_only`
- `assist_only`
- `execute_safe`
- `execute_with_confirmation`
- `full_trusted`

Risk levels (`low|medium|high|critical`) are enforced in tool execution. Medium/high actions can require confirmations depending on profile and safe mode.

## Diagnostics
```bash
littlehive-diag --provider-health
littlehive-diag --failures
littlehive-diag --runtime-stats
littlehive-diag --budget-stats
```

## CLI Entrypoints
- `littlehive-onboard`
- `littlehive-api`
- `littlehive-telegram`
- `littlehive-diag`
- `littlehive-dashboard`
- `littlehive-supervisor`

## Development
```bash
pytest -q
python -m build
twine check dist/*
```

## Limitations
- Dashboard auth is currently basic token gating; default host binding is localhost.
- Provider/tool telemetry is compact summaries by design (no full raw payload dump).

## Roadmap
Phase 6+: richer admin auth, stronger benchmarking, and broader channel/runtime controls.
