Metadata-Version: 2.2
Name: liteswarm
Version: 0.5.1
Summary: A lightweight framework for building AI agent systems
Author-email: Evgenii Mozharovskii <eugene@glyphy.ai>
License: MIT License
        
        Copyright (c) 2025 GlyphyAI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://github.com/GlyphyAI/liteswarm
Project-URL: repository, https://github.com/GlyphyAI/liteswarm
Project-URL: documentation, https://github.com/GlyphyAI/liteswarm#readme
Project-URL: bug-tracker, https://github.com/GlyphyAI/liteswarm/issues
Project-URL: changelog, https://github.com/GlyphyAI/liteswarm/blob/main/CHANGELOG.md
Keywords: ai,agents,llm,swarm,multi-agent,agent-systems,agent-orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: griffe>=1.5.1
Requires-Dist: json-repair>=0.30.2
Requires-Dist: litellm>=1.57.1
Requires-Dist: numpy>=2.2.0
Requires-Dist: orjson>=3.10.11
Requires-Dist: pydantic>=2.10.5
Requires-Dist: prompt_toolkit>=3.0.48
Provides-Extra: dev
Requires-Dist: mypy>=1.14.1; extra == "dev"
Requires-Dist: ruff>=0.7.3; extra == "dev"
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.25.1; extra == "dev"
Requires-Dist: typing-extensions>=4.12.2; extra == "dev"
Requires-Dist: commitizen>=4.1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.3; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.13; extra == "docs"
Requires-Dist: mkdocstrings>=0.24.1; extra == "docs"
Requires-Dist: mkdocstrings-python>=1.9.0; extra == "docs"
Requires-Dist: mdx-truly-sane-lists>=1.3; extra == "docs"
Provides-Extra: examples
Requires-Dist: fastapi>=0.115.6; extra == "examples"
Requires-Dist: uvicorn>=0.34.0; extra == "examples"

# LiteSwarm 🐝

A lightweight, LLM-agnostic framework for building AI agents with dynamic agent switching capabilities. Supports 100+ language models through [litellm](https://github.com/BerriAI/litellm).

> [!WARNING]
> LiteSwarm is currently in early preview and the API is likely to change as we gather feedback.
>
> If you find any issues or have suggestions, please open an issue in the [Issues](https://github.com/glyphyai/liteswarm/issues) section.

## Features

- **Lightweight Core**: Minimal base implementation that's easy to understand and extend
- **LLM Agnostic**: Support for OpenAI, Anthropic, Google, and many more through litellm
- **Dynamic Agent Switching**: Switch between specialized agents during execution
- **Stateful Chat Interface**: Build chat applications with built-in state management
- **Event Streaming**: Real-time streaming of agent responses and tool calls

## Installation

```bash
pip install liteswarm
```

## Requirements

- **Python**: Version 3.11 or higher
- **Async Runtime**: LiteSwarm provides only async API, so you need to use an event loop to run it
- **LLM Provider Key**: You'll need an API key from a supported LLM provider (see [supported providers](https://docs.litellm.ai/docs/providers))
  <details>
  <summary>[click to see how to set keys]</summary>

  ```python
  # Environment variable
  export OPENAI_API_KEY=sk-...
  os.environ["OPENAI_API_KEY"] = "sk-..."
  
  # .env file
  OPENAI_API_KEY=sk-...
  
  # Direct in code
  LLM(model="gpt-4o", key="sk-...")
  ```
  </details>

## Quick Start

All examples below are complete and can be run as is.

### Hello World

Here's a minimal example showing how to use LiteSwarm's core functionality:

```python
import asyncio

from liteswarm.core import Swarm
from liteswarm.types import LLM, Agent, Message


async def main() -> None:
    # Create a simple agent
    agent = Agent(
        id="assistant",
        instructions="You are a helpful assistant.",
        llm=LLM(model="gpt-4o"),
    )

    # Create swarm and execute
    swarm = Swarm()
    result = await swarm.execute(
        agent=agent,
        messages=[Message(role="user", content="Hello!")],
    )
    print(result.agent_response.content)


if __name__ == "__main__":
    asyncio.run(main())
```

### Streaming with Agent Switching

This example demonstrates real-time streaming and dynamic agent switching capabilities:

```python
import asyncio

from liteswarm.core import Swarm
from liteswarm.types import LLM, Agent, Message, ToolResult


# Define a tool that can switch to another agent
def switch_to_expert(domain: str) -> ToolResult:
    return ToolResult.switch_agent(
        agent=Agent(
            id=f"{domain}-expert",
            instructions=f"You are a {domain} expert.",
            llm=LLM(
                model="gpt-4o",
                temperature=0.0,
            ),
        ),
        content=f"Switching to {domain} expert",
    )


async def main() -> None:
    # Create a router agent that can switch to experts
    router = Agent(
        id="router",
        instructions="Route questions to appropriate experts.",
        llm=LLM(
            model="gpt-4o",
            tools=[switch_to_expert],
        ),
    )

    # Stream responses in real-time
    swarm = Swarm()
    stream = swarm.stream(
        agent=router,
        messages=[Message(role="user", content="Explain quantum physics like I'm 5")],
    )

    async for event in stream:
        if event.type == "agent_response_chunk":
            completion = event.response_chunk.completion
            if completion.delta.content:
                print(completion.delta.content, end="", flush=True)
            if completion.finish_reason == "stop":
                print()

    # Optionally, get execution result from stream
    result = await stream.get_return_value()
    print(result.agent_response.content)


if __name__ == "__main__":
    asyncio.run(main())
```

### Stateful Chat

Here's how to build a stateful chat application that maintains conversation history:

```python
import asyncio

from liteswarm.chat import LiteChat
from liteswarm.types import LLM, Agent, SwarmEvent


def handle_event(event: SwarmEvent) -> None:
    if event.type == "agent_response_chunk":
        completion = event.response_chunk.completion
        if completion.delta.content:
            print(completion.delta.content, end="", flush=True)
        if completion.finish_reason == "stop":
            print()


async def main() -> None:
    # Create an agent
    agent = Agent(
        id="assistant",
        instructions="You are a helpful assistant. Provide short answers.",
        llm=LLM(model="gpt-4o"),
    )

    # Create stateful chat
    chat = LiteChat()

    # First message
    print("First message:")
    async for event in chat.send_message("Tell me about Python", agent=agent):
        handle_event(event)

    # Second message - chat remembers the context
    print("\nSecond message:")
    async for event in chat.send_message("What are its key features?", agent=agent):
        handle_event(event)

    # Access conversation history
    messages = await chat.get_messages()
    print(f"\nMessages in history: {len(messages)}")


if __name__ == "__main__":
    asyncio.run(main())
```

For more examples, check out the [examples](examples/) directory. To learn more about advanced features and API details, see our [documentation](docs/).

## Documentation

- [Advanced Features](docs/advanced.md)
- [Examples](docs/examples.md)
- [API Reference](docs/api.md)
- [Contributing](docs/contributing.md)

## Citation

If you use LiteSwarm in your research, please cite our work:

```bibtex
@software{Mozharovskii_LiteSwarm_2025,
    author = {Mozharovskii, Evgenii and {GlyphyAI}},
    license = {MIT},
    month = jan,
    title = {{LiteSwarm}},
    url = {https://github.com/glyphyai/liteswarm},
    version = {0.5.1},
    year = {2025}
}
``` 

## License

MIT License - see [LICENSE](LICENSE) file for details.
