Metadata-Version: 2.4
Name: asterix-agent
Version: 0.2.1
Summary: Stateful AI agents with editable memory blocks and persistent storage
Author-email: Aditya Sarade <aditya.sarade2003@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/adityasarade/Asterix
Project-URL: Documentation, https://github.com/adityasarade/Asterix#readme
Project-URL: Repository, https://github.com/adityasarade/Asterix
Project-URL: Issues, https://github.com/adityasarade/Asterix/issues
Keywords: ai,agents,memory,llm,qdrant,stateful
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Framework :: Pydantic
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.30.0
Requires-Dist: groq>=0.8.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: sentence-transformers>=2.2.2
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# Asterix

**Stateful AI agents with editable memory blocks and persistent storage.**

> **Note:** Asterix is in Beta (v0.2.1). Core features are stable and production-ready.
> Enhanced features and optimizations are in active development.

Asterix is a lightweight Python library for building AI agents that can remember, learn, and persist their state across sessions. No servers required - just `pip install` and start building.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Features

- **Editable Memory Blocks** - Agents can read and write their own memory via built-in tools
- **Persistent Storage** - State saves across sessions (JSON/SQLite backends)
- **Semantic Search** - Qdrant Cloud integration for long-term memory retrieval
- **Enhanced Tool System** - Easy decorator pattern with parameter validation, retry logic, and categories
- **Custom System Prompts** - Override the base system prompt for specialized agent behavior
- **Tool Call Callbacks** - Before/after hooks for human-in-the-loop approval and audit logging
- **Step-by-Step Progress Callbacks** - Stream heartbeat loop progress via `on_step` callback
- **Conversation History API** - Retrieve conversation history with `get_history(limit=)`
- **Auto-Documentation** - Tools automatically generate markdown/JSON documentation
- **Smart Error Handling** - Helpful error messages with suggestions and context
- **Multi-Model Support** - Works with Gemini, Groq, OpenAI, and extensible to others
- **No Server Required** - Pure Python library, runs anywhere

---

## Quick Start

### Installation

```bash
pip install asterix-agent
```

Or with UV (faster):
```bash
uv pip install asterix-agent
```

### Basic Usage

```python
from asterix import Agent, BlockConfig

# Create an agent with custom memory blocks
agent = Agent(
    blocks={
        "task": BlockConfig(size=1500, priority=1),
        "notes": BlockConfig(size=1000, priority=2)
    },
    model="gemini/gemini-2.5-flash"  # Default model
)

# Chat with your agent
response = agent.chat("Hello! Remember that I prefer Python over JavaScript.")
print(response)

# Agent automatically updates its memory
# Memory persists across conversations
```

### Add Custom Tools

```python
@agent.tool(name="read_file", description="Read a file from disk")
def read_file(filepath: str) -> str:
    with open(filepath, 'r') as f:
        return f.read()

# Now your agent can read files
response = agent.chat("Read config.yaml and summarize the settings")
```

### Save & Load State

```python
# Save agent state
agent.save_state()

# Later session - load previous state
agent = Agent.load_state("agent_id")
agent.chat("What were we discussing?")  # Remembers everything!
```

---

## Documentation

Comprehensive documentation is available in the [`docs/`](docs/) directory:

### Core Concepts
- **[Memory System](docs/memory-system.md)** - How agent memory works (blocks, archival, conversation search)
- **[Tool System](docs/tool-system.md)** - Creating and using tools (validation, categories, retry logic)
- **[Storage Backends](docs/storage-backends.md)** - State persistence (JSON, SQLite, custom backends)
- **[Configuration](docs/configuration.md)** - Environment variables, YAML, and Python configuration

### Guides
- **[Examples Guide](docs/examples-guide.md)** - Walkthrough of all examples with explanations
- **[API Reference](docs/api-reference.md)** - Complete API documentation

### Quick Links
- [Environment Setup](docs/configuration.md#environment-variables)
- [YAML Configuration Template](example_agent_config.yaml)
- [Built-in Memory Tools](docs/memory-system.md#built-in-memory-tools)
- [Custom Tool Development](docs/tool-system.md#advanced-tool-development)
- [JSON vs SQLite Backends](docs/storage-backends.md#choosing-a-backend)

---

## Examples

Complete working examples in [`examples/`](examples/):

```bash
# Clone and setup
git clone https://github.com/adityasarade/Asterix.git
cd Asterix && pip install -e .

# Run examples
python examples/basic_chat.py              # Simple conversation
python examples/custom_tools.py            # Tool registration
python examples/persistent_agent.py        # JSON persistence
python examples/persistent_agent_sqlite.py # SQLite persistence
python examples/cli_agent.py               # Full-featured CLI
```

See the **[Examples Guide](docs/examples-guide.md)** for detailed walkthroughs.

---

## 🧪 Testing

```bash
pip install -e ".[dev]"
pytest --cov=asterix --cov-report=html
```

---

## Project Status

**Current Version:** 0.2.1 (Beta)

**Roadmap:**
- [x] Core agent implementation
- [x] Memory tools system
- [x] State persistence (JSON & SQLite)
- [x] Qdrant integration
- [x] Enhanced tool system with validation
- [x] Auto-documentation
- [x] Multi-model support (Gemini, Groq, OpenAI)
- [x] OSCAR integration (callbacks, system prompts, history API)
- [x] Gemini SDK migration (`google-genai` v1.x)
- [x] Vertex AI support (dual-mode Gemini auth)
- [ ] Performance optimizations
- [ ] Advanced monitoring
- [ ] Streaming responses
- [ ] Multi-agent collaboration
- [ ] Additional backends (Redis, PostgreSQL)

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/your-feature`)
3. Commit your changes (`git commit -m 'Add your feature'`)
4. Push to the branch (`git push origin feature/your-feature`)
5. Open a Pull Request

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## Acknowledgments

- Built with [Gemini](https://ai.google.dev/), [Groq](https://groq.com/), and [OpenAI](https://openai.com/)
- Vector storage by [Qdrant](https://qdrant.tech/)
- Inspired by [Letta](https://www.letta.com/)

---

## Support

- **Documentation:** [Full documentation](docs/) with guides and API reference
- **Issues:** [GitHub Issues](https://github.com/adityasarade/Asterix/issues) - Report bugs or request features
- **Examples:** [Examples directory](examples/) - Working code examples
- **Changelog:** [CHANGELOG.md](CHANGELOG.md) - Version history and updates

---

**So that everyone can build better agents without worrying about memory (Let's hope OpenAI doesn't make this library meaningless)**
