entity-core 0.0.12
A flexible, plugin-based framework for building AI agents
License: MIT
Requires Python: >=3.11
Keywords: ai, agents, llm, framework, plugin, workflow, memory, rag, autonomous, assistant

# Entity Framework 🚀
### Build Production-Ready AI Agents 10x Faster

[![PyPI version](https://badge.fury.io/py/entity-core.svg)](https://badge.fury.io/py/entity-core)
[![Documentation Status](https://readthedocs.org/projects/entity-core/badge/?version=latest)](https://entity-core.readthedocs.io/en/latest/?badge=latest)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/Ladvien/entity/workflows/tests/badge.svg)](https://github.com/Ladvien/entity/actions)
[![Coverage](https://codecov.io/gh/Ladvien/entity/branch/main/graph/badge.svg)](https://codecov.io/gh/Ladvien/entity)

---

## 🎯 Why Entity Framework?

**Stop fighting with boilerplate. Start building intelligent agents.**

Entity transforms AI development from a complex engineering challenge into simple, composable components. While other frameworks force you to write thousands of lines of coupled code, Entity's revolutionary plugin architecture lets you build production-ready agents in hours, not weeks.

```python
# Traditional approach: 2000+ lines of code, 2-3 weeks
# Entity approach: This is it. Seriously.

from entity import Agent
agent = Agent.from_config("your_agent.yaml")
await agent.chat("")  # Interactive intelligent agent with memory, tools, safety
```

## 🔥 What Makes Entity Different

| Feature | Traditional Frameworks | **Entity Framework** |
|---------|----------------------|---------------------|
| **Development Time** | 2-3 weeks | **2-3 days** |
| **Lines of Code** | 2000+ lines | **200 lines** |
| **Architecture** | Monolithic, coupled | **Plugin-based, modular** |
| **Configuration** | Code changes required | **YAML-driven** |
| **Testing** | Complex integration tests | **Simple unit tests** |
| **Team Collaboration** | Sequential development | **Parallel plugin development** |
| **Maintenance** | Fragile, risky changes | **Isolated, safe updates** |
| **Production Ready** | DIY monitoring/safety | **Built-in observability** |

## ⚡ 30-Second Quickstart

```bash
# Install Entity
pip install entity-core

# Run your first agent
python -c "
from entity import Agent
from entity.defaults import load_defaults

agent = Agent(resources=load_defaults())
print('🤖 Agent ready! Try: Hello, tell me a joke')
"
```

That's it. You now have a production-ready AI agent with:
- 🧠 **Local LLM** (Ollama) or cloud APIs
- 💾 **Persistent memory** with conversation history
- 🛡️ **Built-in safety** and error handling
- 📊 **Automatic logging** and monitoring
- 🔧 **Zero configuration** required

## 🎨 Progressive Examples

### Hello World Agent (3 lines)
```python
from entity import Agent
from entity.defaults import load_defaults

agent = Agent(resources=load_defaults())
response = await agent.chat("Hello!")  # "Hi! How can I help you today?"
```

### Agent with Custom Personality (5 lines)
```python
from entity import Agent

agent = Agent.from_config("personality_config.yaml")
# YAML defines: role="You are a helpful Python tutor"
response = await agent.chat("Explain decorators")  # Detailed Python tutorial
```

### Agent with Tools (10 lines)
```python
from entity import Agent
from entity.tools import WebSearchTool, CalculatorTool

agent = Agent.from_config("tools_config.yaml")
# YAML enables: web_search, calculator, file_operations
response = await agent.chat("Search for Python 3.12 features and calculate 15% of 200")
# Executes web search, performs calculation, provides comprehensive answer
```

### Multi-Agent Collaboration (15 lines)
```python
from entity import Agent, AgentOrchestrator

# Create specialized agents
researcher = Agent.from_config("researcher_config.yaml")
writer = Agent.from_config("writer_config.yaml")
reviewer = Agent.from_config("reviewer_config.yaml")

# Orchestrate workflow
orchestrator = AgentOrchestrator([researcher, writer, reviewer])
result = await orchestrator.execute("Write a technical blog post about Entity Framework")
# Researcher gathers info → Writer creates post → Reviewer refines → Final result
```

### Production Configuration (Complete system)
```python
from entity import Agent
from entity.monitoring import setup_observability

# Production-ready agent with full observability
agent = Agent.from_config("production_config.yaml")
setup_observability(agent, metrics=True, alerts=True, tracing=True)

# YAML configures: clustering, load balancing, database, monitoring, safety filters
await agent.serve(host="0.0.0.0", port=8000)  # Production API server
```

## 🏗️ The Entity Architecture

Entity's revolutionary **6-stage plugin pipeline** transforms how you build AI applications:

### The Pipeline Flow

**📝 INPUT** → **📊 PARSE** → **🧠 THINK** → **🔧 DO** → **✅ REVIEW** → **📤 OUTPUT**

### Stage Details

#### 📝 **Stage 1: INPUT**
> **Receive and process incoming data**
- Handles: Text, Files, Images, URLs, Voice, Data
- Plugins: Input Adapters
- Purpose: Accept any input format seamlessly

#### 📊 **Stage 2: PARSE**
> **Understand and structure the input**
- Handles: Language Analysis, Structure, Metadata
- Plugins: Parsers
- Purpose: Extract meaning and context

#### 🧠 **Stage 3: THINK**
> **Reason about the task**
- Handles: Context Synthesis, Planning, Strategy
- Plugins: Reasoning Engines
- Purpose: Decide best approach

#### 🔧 **Stage 4: DO**
> **Execute actions and operations**
- Handles: Tools, Search, Analysis, APIs
- Plugins: Tool Executors
- Purpose: Perform the actual work

#### ✅ **Stage 5: REVIEW**
> **Validate and ensure quality**
- Handles: Quality, Safety, Compliance
- Plugins: Validators
- Purpose: Guarantee correct output

#### 📤 **Stage 6: OUTPUT**
> **Deliver results to users**
- Handles: Reports, APIs, Dashboards
- Plugins: Output Formatters
- Purpose: Present results effectively

**Each stage is customizable through plugins**:
- 🔌 **Modular**: One plugin = one responsibility
- 🔄 **Composable**: Mix and match for any use case
- ✅ **Testable**: Unit test plugins independently
- ⚙️ **Configurable**: YAML changes behavior, not code
- 🔄 **Reusable**: Share plugins across projects

## 🚀 Installation Options

### Quick Install (Recommended)
```bash
pip install entity-core
```

### With Optional Dependencies
```bash
# Web tools and advanced features
pip install "entity-core[web,advanced]"

# Development tools
pip install "entity-core[dev]"

# Everything
pip install "entity-core[all]"
```

### Using UV (Fastest)
```bash
uv add entity-core
```

### Using Poetry
```bash
poetry add entity-core
```

### From Source
```bash
git clone https://github.com/Ladvien/entity.git
cd entity
pip install -e .
```

## 🎓 Learning Path

### 🌱 **Beginner** (10 minutes)
1. **[Quick Start](docs/quickstart.md)** - Your first agent in 5 minutes
2. **[Basic Examples](examples/)** - Simple, working examples
3. **[Core Concepts](docs/concepts.md)** - Understanding the architecture

### 🌿 **Intermediate** (1 hour)
1. **[Plugin Development](docs/plugins.md)** - Build custom capabilities
2. **[Configuration Guide](docs/configuration.md)** - Master YAML workflows
3. **[Production Patterns](examples/production/)** - Real-world applications

### 🌲 **Advanced** (1 day)
1. **[Multi-Agent Systems](docs/orchestration.md)** - Complex workflows
2. **[Performance Optimization](docs/performance.md)** - Scale to production
3. **[Contributing](CONTRIBUTING.md)** - Join the community

## 💼 Real-World Use Cases

### Customer Support Bot
```yaml
# config/support_agent.yaml
plugins:
  input: [text, email, chat]
  knowledge: [company_docs, faq_database]
  actions: [ticket_creation, escalation]
  output: [formatted_response, internal_notes]
```

### Code Review Agent
```yaml
# config/code_reviewer.yaml
plugins:
  input: [github_pr, file_diff, code_snippet]
  analysis: [security_scan, style_check, complexity]
  actions: [inline_comments, suggestions]
  output: [review_summary, action_items]
```

### Research Assistant
```yaml
# config/researcher.yaml
plugins:
  input: [research_query, document_upload]
  sources: [web_search, academic_papers, internal_docs]
  analysis: [fact_checking, synthesis, citation]
  output: [report_generation, bibliography]
```

## 🏆 Why Teams Choose Entity

### 🚀 **Startups**: Ship Faster
- **MVP in days**: Plugin architecture accelerates development
- **Easy pivoting**: Swap plugins without rewriting core logic
- **Cost effective**: Local-first reduces API costs

### 🏢 **Enterprises**: Scale Safely
- **Standardization**: Consistent patterns across all AI projects
- **Compliance ready**: Built-in safety, auditing, monitoring
- **Team productivity**: Parallel development of isolated plugins

### 🎓 **Education**: Learn Better
- **Best practices**: Plugin architecture teaches good software design
- **Gradual complexity**: Start simple, add features incrementally
- **Real projects**: Build agents that solve actual problems

## 🔗 Resources & Community

### 📚 **Documentation**
- **[Full Documentation](https://entity-core.readthedocs.io/)** - Complete guides and API reference
- **[Examples Gallery](examples/)** - From "Hello World" to production systems
- **[Cookbook](docs/cookbook.md)** - Common patterns and recipes

### 💬 **Community**
- **[GitHub Discussions](https://github.com/Ladvien/entity/discussions)** - Q&A and feature requests
- **[GitHub Issues](https://github.com/Ladvien/entity/issues)** - Bug reports and feature tracking

### 🤝 **Contributing**
- **[Contribution Guide](CONTRIBUTING.md)** - How to help improve Entity
- **[Plugin Registry](https://plugins.entity.dev)** - Share and discover plugins
- **[Roadmap](ROADMAP.md)** - What's coming next
- **[Governance](GOVERNANCE.md)** - Project decision-making

## 📊 Performance & Benchmarks

Entity is designed for both developer productivity and runtime performance:

- **🚀 10x Development Speed**: Plugin architecture eliminates boilerplate
- **⚡ Low Latency**: Optimized plugin execution pipeline
- **📈 Horizontal Scale**: Stateless design supports clustering
- **💾 Memory Efficient**: Persistent storage with intelligent caching
- **🔍 Observable**: Built-in metrics, tracing, and debugging

See detailed benchmarks in [docs/performance.md](docs/performance.md).

## 🛡️ Security & Privacy

Entity prioritizes security and privacy:

- **🏠 Local First**: Runs entirely on your infrastructure
- **🔒 Secure by Default**: Input validation, output sanitization
- **🛡️ Sandboxed Tools**: Isolated execution environments
- **📋 Audit Trails**: Comprehensive logging for compliance
- **🔐 Secrets Management**: Secure configuration and key handling

See our [Security Policy](SECURITY.md) for details.


## ❤️ Acknowledgments

Entity Framework is built with love by the open-source community. Special thanks to:

- **Core Contributors**: [List of contributors](CONTRIBUTORS.md)
- **Inspiration**: LangChain, AutoGen, CrewAI for pioneering agent frameworks
- **Community**: Our amazing GitHub community for feedback and contributions
- **Sponsors**: Organizations supporting Entity's development

## 📄 License

Entity Framework is released under the [MIT License](LICENSE).

---

<div align="center">

**Ready to build the future of AI?**

[📚 Read the Docs](https://entity-core.readthedocs.io/) •
[🚀 Quick Start](docs/quickstart.md) •
[🐙 GitHub](https://github.com/Ladvien/entity)

**Entity Framework**: *Build better AI agents, faster.* 🚀

</div>