Metadata-Version: 2.4
Name: llm-gent
Version: 0.4.0
Summary: Agent framework with learning capabilities
Author-email: LLM Works LLC <info@llm-works.ai>
License: Apache-2.0
Project-URL: Homepage, https://github.com/llm-works/llm-gent
Project-URL: Documentation, https://github.com/llm-works/llm-gent#readme
Project-URL: Repository, https://github.com/llm-works/llm-gent
Keywords: agents,llm,ai,learning
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alembic>=1.13
Requires-Dist: appinfra>=0.13.0
Requires-Dist: cattrs>=23.0
Requires-Dist: httpx>=0.27
Requires-Dist: llm-infer>=0.8.0
Requires-Dist: llm-kelt>=0.5.0
Requires-Dist: llm-saia>=0.6.3
Requires-Dist: pydantic>=2.0
Requires-Dist: pyzmq>=26.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: SQLAlchemy<2.1,>=2.0
Requires-Dist: trafilatura>=2.0
Provides-Extra: http
Requires-Dist: appinfra[fastapi]>=0.13.0; extra == "http"
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-xdist>=3.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: types-PyYAML<7.0,>=6.0; extra == "dev"
Dynamic: license-file

# llm-gent

Agent framework with trait-based architecture and learning capabilities.

## Overview

llm-gent provides a composable framework for building LLM-powered agents. Agents are composed of
**traits** that provide specific capabilities (LLM access, storage, learning, etc.) and can be
run standalone or as services via the included HTTP runtime.

Key features:

- **Trait-based composition** - Mix and match capabilities via traits (LLM, Storage, Rating, Learn)
- **Multi-backend LLM support** - OpenAI-compatible, Anthropic, and custom backends via llm-infer
- **Built-in learning** - Collect training data (SFT/DPO) and fine-tune via llm-kelt
- **Structured output** - Pydantic schema validation with automatic JSON cleanup for small models
- **Production ready** - HTTP server, PostgreSQL storage, schema migrations

## Installation

```bash
pip install llm-gent
```

For HTTP server support:

```bash
pip install llm-gent[http]
```

## Supported Python versions

CI tests against Python **3.11**, **3.12**, **3.13**, and **3.14** on every
push. `requires-python = ">=3.11"`.

## Quick Start

```python
from appinfra.log import create_lg

from llm_gent import AgentFactory, LLMTrait

lg = create_lg("my-agent", "info")

agent = AgentFactory(lg).from_config(
    {
        "identity": {"name": "my-agent"},
        "llm": {
            "default": "local",
            "backends": {
                "local": {
                    "type": "openai_compatible",
                    "base_url": "http://localhost:8000/v1",
                    "model": "default",
                }
            },
        },
        "directive": "You are a helpful assistant.",
        "traits": {"required": ["llm", "directive"]},
    }
)

agent.start()
llm = agent.require_trait(LLMTrait)
result = llm.complete([{"role": "user", "content": "Hello!"}])
print(result.content)
agent.stop()
```

A runnable version of this example lives at `llm_gent/examples/quickstart.py`. Pass
`--smoke` to run it against a stub LLM router (no real backend contacted).

## Core Concepts

### Agents

An `Agent` is a container for traits with lifecycle management. Agents have an identity
(`name` plus optional `context_key`) and can be started, stopped, and — via
`RunnableAgent` — run in cycles.

### Traits

Traits provide specific capabilities to agents:

| Trait | Purpose |
|-------|---------|
| `LLMTrait` | LLM completions with multi-backend routing |
| `DirectiveTrait` | System prompts and agent instructions |
| `StorageTrait` | PostgreSQL persistence with migrations |
| `RatingTrait` | Automated LLM-based content evaluation |
| `LearnTrait` | Training data collection (SFT/DPO) |
| `ToolsTrait` | Tool/function calling support |

### Tools

Built-in tools for agentic workflows:

- `ShellTool` - Execute shell commands
- `FileReadTool` / `FileWriteTool` - File operations
- `HTTPFetchTool` - HTTP requests
- `RecallTool` / `RememberTool` - Memory operations

## Running as a Service

```bash
# Start agent server (uses packaged default config)
llm-gent serve

# With custom config
llm-gent --config path/to/config.yaml serve
```

## Related Projects

- [llm-infer](https://github.com/llm-works/llm-infer) - LLM inference server and client
- [llm-kelt](https://github.com/llm-works/llm-kelt) - Training infrastructure (SFT/DPO)
- [appinfra](https://github.com/llm-works/appinfra) - Application infrastructure utilities

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

Maintained by [LLM Works LLC](https://llm-works.ai) and contributors.
