Metadata-Version: 2.4
Name: lightagentx
Version: 0.1.0
Summary: A lightweight, modular agentic AI framework built from scratch — no LangChain, no CrewAI, no magic.
Author: Devansh
License: MIT
Project-URL: Homepage, https://github.com/devansh/lightagentx
Project-URL: Repository, https://github.com/devansh/lightagentx
Project-URL: Documentation, https://github.com/devansh/lightagentx/blob/main/docs/guide.md
Project-URL: Issues, https://github.com/devansh/lightagentx/issues
Keywords: ai,agent,llm,framework,langchain,crewai,openai,tool-calling,multi-agent,react
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

<p align="center">
  <h1 align="center">⚡ LightAgentX</h1>
  <p align="center">
    A lightweight, modular agentic AI framework built from scratch.<br>
    No LangChain. No CrewAI. No magic. Just clean Python.
  </p>
</p>

<p align="center">
  <a href="https://pypi.org/project/lightagentx/"><img src="https://img.shields.io/pypi/v/lightagentx?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/lightagentx/"><img src="https://img.shields.io/pypi/pyversions/lightagentx" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
</p>

---

## What is LightAgentX?

LightAgentX is a **~1,200 line** Python framework that rebuilds every core pattern from LangChain and CrewAI from first principles — LLM abstraction, memory, tools, planning, the agent loop, and multi-agent orchestration.

Every module is transparent, composable, and designed to teach you exactly what happens when an AI agent "thinks", "remembers", or "uses a tool".

```
lightagentx/
├── llm/          LLM abstraction (swap providers without changing agent code)
├── memory/       Conversation memory (buffer + LLM-compressed summary)
├── tools/        Tool system (@tool decorator → JSON Schema → execution)
├── planning/     ReAct reasoning (Thought → Action → Observation)
├── loop/         Core agent loop (the heart of ALL agentic frameworks)
├── agents/       Single agents, sequential pipelines, crew orchestration
└── utils/        Colored logger for tracing
```

---

## Installation

```bash
pip install lightagentx
```

Or install from source:

```bash
git clone https://github.com/devansh/lightagentx.git
cd lightagentx
pip install -e .
```

---

## Quick Start

```python
from lightagentx import OpenAILLM, SingleAgent, tool

# 1. Create an LLM
llm = OpenAILLM()  # uses OPENAI_API_KEY env var

# 2. Define tools
@tool
def calculate(expression: str) -> str:
    """Evaluate a math expression.

    Args:
        expression: A math expression like '2 + 3 * 4'.
    """
    return str(eval(expression))

# 3. Create an agent
agent = SingleAgent(name="MathBot", llm=llm, tools=[calculate])

# 4. Run it
print(agent.run("What is 25 * 37?"))
# → "25 × 37 = 925"
```

> **📖 Full usage guide →** [docs/guide.md](docs/guide.md)

---

## Features

| Feature | Description |
|---|---|
| 🔌 **Pluggable LLMs** | Swap between OpenAI, Anthropic, or any provider via `BaseLLM` |
| 🧠 **Memory** | `BufferMemory` (sliding window) and `SummaryMemory` (LLM-compressed) |
| 🔧 **Tools** | `@tool` decorator auto-generates JSON Schema from type hints |
| 🧪 **ReAct Planning** | Thought → Action → Observation reasoning loop |
| ⚙️ **Agent Loop** | The universal LLM → decide → execute → observe loop |
| 👥 **Multi-Agent** | Sequential pipelines and hierarchical crew delegation |
| 🎨 **Colored Logger** | Visual trace of every agent decision |

---

## Examples

```bash
# Basic chat with memory
python examples/01_basic_chat.py

# Agent with tools (calculator, weather, time)
python examples/02_tool_agent.py

# ReAct reasoning loop
python examples/03_react_agent.py

# Multi-agent pipelines + crew
python examples/04_multi_agent.py
```

---

## Testing

All tests use mocked LLM responses — **no API key required**:

```bash
pip install -e ".[dev]"
python -m pytest tests/ -v
```

```
72 passed in 0.96s ✅
```

---

## How It Maps to LangChain & CrewAI

| LightAgentX | LangChain | CrewAI |
|---|---|---|
| `BaseLLM` / `OpenAILLM` | `BaseChatModel` / `ChatOpenAI` | — |
| `BufferMemory` | `ConversationBufferWindowMemory` | — |
| `SummaryMemory` | `ConversationSummaryMemory` | — |
| `@tool` / `BaseTool` | `@tool` / `StructuredTool` | `@tool` |
| `ToolRegistry` | `format_tool_to_openai_function()` | — |
| `AgentLoop` | `AgentExecutor.invoke()` | Agent loop |
| `SingleAgent` | `create_tool_calling_agent` + `AgentExecutor` | `Agent` |
| `SequentialPipeline` | `SequentialChain` / LCEL pipes | `Crew(process=sequential)` |
| `CrewAgent` | — | `Crew(process=hierarchical)` |

---

## Architecture

```
Dependency flow (each layer only knows about layers below it):

  logger → llm → memory → tools → planning → loop/engine → agents
```

Design patterns used:
- **Strategy** — `BaseLLM`, `BaseMemory`, `BasePlanner` (swappable implementations)
- **Decorator** — `@tool` converts functions into tool objects
- **Composite** — Pipelines and crews are agents themselves (nestable)

---

## License

MIT — see [LICENSE](LICENSE).
