entity-core 0.0.11

A flexible, plugin-based framework for building AI agents

Entity Framework 🚀

Build Production-Ready AI Agents 10x Faster

---

🎯 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.

# 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

# 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)

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)

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)

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)

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)

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)

pip install entity-core

With Optional Dependencies

# 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)

uv add entity-core

Using Poetry

poetry add entity-core

From Source

git clone https://github.com/Ladvien/entity.git
cd entity
pip install -e .

🎓 Learning Path

🌱 Beginner (10 minutes)

1. Quick Start - Your first agent in 5 minutes
2. Basic Examples - Simple, working examples
3. Core Concepts - Understanding the architecture

🌿 Intermediate (1 hour)

1. Plugin Development - Build custom capabilities
2. Configuration Guide - Master YAML workflows
3. Production Patterns - Real-world applications

🌲 Advanced (1 day)

1. Multi-Agent Systems - Complex workflows
2. Performance Optimization - Scale to production
3. Contributing - Join the community

💼 Real-World Use Cases

Customer Support Bot

# 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

# 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

# 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 - Complete guides and API reference
• Examples Gallery - From "Hello World" to production systems
• Cookbook - Common patterns and recipes

💬 Community

• GitHub Discussions - Q&A and feature requests
• GitHub Issues - Bug reports and feature tracking

🤝 Contributing

• Contribution Guide - How to help improve Entity
• Plugin Registry - Share and discover plugins
• Roadmap - What's coming next
• Governance - 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.

🛡️ 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 for details.

❤️ Acknowledgments

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

• Core Contributors: List of contributors
• 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.

---

Ready to build the future of AI?

📚 Read the Docs • 🚀 Quick Start • 🐙 GitHub

Entity Framework: Build better AI agents, faster. 🚀