Metadata-Version: 2.4
Name: uc-llm-agent-tools
Version: 0.2.0
Summary: Lightweight LLM agent library — memory layers, skills, context engineering
Project-URL: Homepage, https://github.com/cuber-it/llm-agent-tools
Project-URL: Repository, https://github.com/cuber-it/llm-agent-tools
Project-URL: Changelog, https://github.com/cuber-it/llm-agent-tools/blob/master/CHANGELOG.md
Author-email: uc-it <sonstige@uc-it.de>
License: MIT
Keywords: agent,ai,context-engineering,llm,memory,react,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: uc-llm-provider>=0.5.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# uc-llm-agent-tools

**Lightweight LLM agent library** — memory layers, skills, context engineering.

Works with any LLM: Anthropic, OpenAI, Google, Ollama.
Built on [uc-llm-provider](https://pypi.org/project/uc-llm-provider/).

[![PyPI](https://img.shields.io/pypi/v/uc-llm-agent-tools)](https://pypi.org/project/uc-llm-agent-tools/)
[![Python](https://img.shields.io/pypi/pyversions/uc-llm-agent-tools)](https://pypi.org/project/uc-llm-agent-tools/)
[![License](https://img.shields.io/pypi/l/uc-llm-agent-tools)](LICENSE)

---

## Why

Most agent frameworks are complex, opinionated, and hard to embed.
`uc-llm-agent-tools` is a small, composable library:

- **No mandatory vector DB** — SQLite by default
- **No framework lock-in** — works with any provider via `uc-llm-provider`
- **Context Engineering first** — token budget, anti-fail guards built in
- **Readable memory** — Identity and memories are Markdown files

## Install

```bash
pip install uc-llm-agent-tools
```

## Quick Start

```python
import asyncio
from llm_agent_tools import Agent, Identity, MemoryStore, MemoryLayer, skill, SkillResult
from llm_agent_tools.memory.backends.sqlite import SQLiteBackend
from uc_llm_provider import get_provider

# Define a skill
@skill(name="fetch_page", description="Fetch and analyze a web page", tags=["browser"])
async def fetch_page(url: str) -> SkillResult:
    # your implementation here
    return SkillResult(success=True, content=f"Page at {url} analyzed", data={})

# Create agent
agent = Agent(
    identity = Identity.from_file("my-identity.md"),
    memory   = MemoryStore(
        backend = SQLiteBackend("agent.sqlite3"),
        layers  = [
            MemoryLayer("project", level=2, persist=True),
            MemoryLayer("run",     level=3, persist=False),
        ]
    ),
    skills   = [fetch_page],
    provider = get_provider({"name": "anthropic", "provider_type": "anthropic"}),
)

async def main():
    result = await agent.run("Analyze https://example.com for accessibility issues")
    print(result.response)

asyncio.run(main())
```

## Identity File

```markdown
---
name: My Agent
version: 1.0
---

# Persönlichkeit

I am a QA specialist. I test systematically and precisely.

# Direktiven

- Never test production systems without explicit confirmation.
- Always report errors — never swallow them silently.
```

Directives are **immutable at runtime**. Personality grows via `agent.identity.add_fact(...)`.

## Memory Hierarchy

```
Level 0: Directives   — always loaded, never overridden
Level 1: Personality  — always loaded, grows over time
Level N: custom named — filtered by budget and relevance
```

High beats low. Low complements high.

## Context Engineering

`ContextBuilder` prevents the four context failure modes automatically:

| Guard | Problem prevented |
|---|---|
| **Poisoning Guard** | LLM-sourced memories are marked `[LLM]` |
| **Distraction Guard** | Run-memory capped when context grows too large |
| **Confusion Guard** | Max 8 skills loaded at once |
| **Clash Guard** | Hierarchy enforces priority |

## ThinkingLight

Provider-independent Chain-of-Thought — works on Ollama, GPT, Claude alike.
No expensive Extended Thinking required.

```python
from llm_agent_tools import wrap_prompt, extract_thinking

prompt   = wrap_prompt("Analyze this page")
thinking, answer = extract_thinking(llm_response)
```

## Human-in-the-Loop

```python
from llm_agent_tools import HumanInTheLoop

hitl = HumanInTheLoop(on_pause=my_approval_handler)
decision = await hitl.pause(
    message  = "I found 47 test ideas. Generate all as Gherkin?",
    options  = ["All", "High priority only", "Cancel"],
    timeout  = 300,
    fallback = "High priority only",
)
```

## Structured Output

```python
from llm_agent_tools import structured_ai
from pydantic import BaseModel

class TestReport(BaseModel):
    summary: str
    issues:  list[str]

report = await structured_ai(provider, "Analyze this page", TestReport)
# report is a validated TestReport instance
```

## Interactive Session

```python
session = agent.interactive_session()
response = await session.chat("Why did you choose that selector?")
response = await session.chat("Now test the login form specifically")
```

## License

MIT — [uc-it](https://uc-it.de)
