Eion Python SDK
Python SDK for Eion - Shared memory storage and collaborative intelligence for AI agent systems.
Table of Contents
- Prerequisites
- Installation
- Quick Start
- Cluster Management
- Agent Memory Operations
- API Reference
- Troubleshooting
- Configuration
- Features
- License
Prerequisites
Before using this SDK, you need to have an Eion server running. This SDK is a client that connects to your Eion server instance.
Docker
# 1. Create a docker-compose.yml file
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
eion-server:
image: eiondb/eion:latest
ports:
- "8080:8080"
environment:
- DATABASE_URL=postgres://eion:password@postgres:5432/eion
- CLUSTER_API_KEY=my-secret-api-key-123 # You choose this!
depends_on:
- postgres
postgres:
image: postgres:15
environment:
- POSTGRES_DB=eion
- POSTGRES_USER=eion
- POSTGRES_PASSWORD=password
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:
EOF
# 2. Start the Eion server
docker-compose up -d
# 3. Verify it's running
curl http://localhost:8080/health
Installation
pip install eiondb
Or install from source:
git clone https://github.com/eiondb/eion-sdk-python.git
cd eion-sdk-python
pip install -e .
Quick Start
1. Setup Eion Server (One-time)
from eiondb import EionClient
# Setup server infrastructure (downloads ~3GB on first run)
client = EionClient()
client.setup() # Downloads Docker images, Python packages, AI models
2. Run the Server
# Option A: Run in background (recommended for development)
client.run(detached=True)
# Option B: Run in foreground (blocks terminal)
client.run() # Press Ctrl+C to stop
3. Use Cluster Management
# Create users and agents
client.create_user("user1", "John Doe")
client.register_agent("agent1", "Assistant", permission="crud")
client.create_session("session1", "user1")
# Check server health
if client.server_health():
print("✅ Server is ready!")
4. Agent Memory Operations
Agents use HTTP endpoints directly for memory operations:
# Agent stores memory
curl -X POST "http://localhost:8080/sessions/v1/session1/memories?agent_id=agent1&user_id=user1" \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "I like pizza"}]}'
# Agent retrieves shared memory
curl "http://localhost:8080/sessions/v1/session1/memories?agent_id=agent1&user_id=user1&last_n=10"
# Agent searches knowledge
curl "http://localhost:8080/sessions/v1/session1/memories/search?agent_id=agent1&user_id=user1&query=pizza"
Cluster Management
The SDK provides cluster-level management for developers:
User Management
# Create user
user = client.create_user(
user_id="user123",
name="John Doe" # Optional
)
# Delete user
client.delete_user("user123")
Agent Management
# Register agent
agent = client.register_agent(
agent_id="agent123",
name="Assistant Agent",
permission="crud", # c=create, r=read, u=update, d=delete
description="AI assistant for customer support"
)
# Update agent
client.update_agent("agent123", "permission", "r")
# Delete agent
client.delete_agent("agent123")
# List agents
agents = client.list_agents()
Session Management
# Create session
session = client.create_session(
session_id="session123",
user_id="user123",
session_name="Support Chat" # Optional
)
# Delete session
client.delete_session("session123")
Agent Groups
# Create agent group
group = client.register_agent_group(
group_id="support_team",
name="Support Team",
agent_ids=["agent1", "agent2"],
description="Customer support agents"
)
# Update group
client.update_agent_group("support_team", "agent_ids", ["agent1", "agent2", "agent3"])
Agent Memory Operations
Important: Agents use HTTP endpoints directly, not Python SDK methods.
Memory Storage
# Store conversation memory with automatic knowledge extraction
curl -X POST "http://localhost:8080/sessions/v1/{session_id}/memories?agent_id={agent_id}&user_id={user_id}" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "I want to order pizza"},
{"role": "assistant", "content": "What toppings would you like?"}
]
}'
Memory Retrieval
# Get recent conversation history
curl "http://localhost:8080/sessions/v1/{session_id}/memories?agent_id={agent_id}&user_id={user_id}&last_n=20"
Knowledge Search
# Search shared knowledge across agents
curl "http://localhost:8080/sessions/v1/{session_id}/memories/search?agent_id={agent_id}&user_id={user_id}&query=pizza+order"
Multi-Agent Memory Sharing
All agents in the same session share memory and knowledge:
# Setup shared session
client.create_session("shared_session", "user1")
# Agent 1 stores memory → automatically shared
# Agent 2 can retrieve Agent 1's memory
# Agent 3 can search across all agents' knowledge
API Reference
EionClient
Server Management
setup(force_reset=False)- Setup server infrastructurerun(detached=False)- Run the serverstop()- Stop the serverreset()- Reset to clean stateserver_health()- Check server health
Cluster Management
create_user(user_id, name=None)delete_user(user_id)register_agent(agent_id, name, permission='r', description=None)update_agent(agent_id, field, value)delete_agent(agent_id)list_agents(permission=None)create_session(session_id, user_id, session_name=None)delete_session(session_id)register_agent_group(group_id, name, agent_ids=[], description=None)
Configuration
Default Configuration
On first setup, eion.yaml is created with defaults:
common:
http:
host: "0.0.0.0"
port: 8080
postgres:
user: "eion"
password: "eion_pass"
host: "localhost"
port: 5432
database: "eion"
neo4j:
uri: "bolt://localhost:7687"
username: "neo4j"
password: "password"
Custom Configuration
Edit eion.yaml to customize:
common:
http:
port: 8090 # Change server port
postgres:
password: "my_secure_password" # Change database password
Environment Variables
export EION_CLUSTER_API_KEY="your-secret-key"
export EION_BASE_URL="http://localhost:8080"
Troubleshooting
Setup Issues
"Docker not found"
# Install Docker Desktop
# macOS: brew install --cask docker
# Or download from https://docker.com
"Port 8080 already in use"
# Find process using port
lsof -i :8080
# Kill process or change port in eion.yaml
"Insufficient disk space"
- Need at least 3GB free space for all dependencies
Runtime Issues
"Server not responding"
# Check if server is running
client.server_health()
# Restart server
client.stop()
client.run(detached=True)
"Authentication failed"
- Make sure
cluster_api_keyis set correctly - Check
eion.yamlconfiguration
Reset and Clean Start
# Complete reset
client.reset()
client.setup()
client.run(detached=True)
System Requirements
- Python: 3.7 or higher
- Docker: Latest version with Docker Compose
- Disk Space: 3GB free space
- Memory: 4GB RAM recommended
- Ports: 5432, 7474, 7687, 8080 available
Architecture
Eion provides:
- 🗄️ PostgreSQL + pgvector: Message storage and vector search
- 🕸️ Neo4j + APOC: Knowledge graph with temporal reasoning
- 🤖 Real Embeddings:
all-MiniLM-L6-v2model (384 dimensions) - 🧠 Knowledge Extraction: Automatic entity/relationship extraction
- ⚡ Multi-Agent Memory: Shared memory across agent sessions
- 🔄 Conflict Resolution: Automatic temporal conflict handling
Features
- Cluster Management: User, agent, and session management
- Agent Registration: Register and manage AI agents with permissions
- Session Management: Create and manage conversation sessions
- Agent Groups: Organize agents into teams
- Session Types: Define session templates with agent group assignments
- Monitoring & Analytics: Track agent performance and collaboration
- Health Checks: Monitor system health and connectivity
- Structured Error Handling: Comprehensive exception types
- Authentication: Multiple authentication methods
- Type Hints: Full type annotation support
Documentation
- Full API Documentation: docs/openapi.yaml
- Agent API Guide: docs/agent-api-guide.json
- Examples: example/
Support
- Issues: GitHub Issues
License
This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE.md file for details.
Happy building with Eion! 🚀
Metadata
Release files for eiondb 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| eiondb-0.1.4.tar.gz | 27.8 kB | Without provenance | Details for eiondb-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| eiondb-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for eiondb-0.1.4-py3-none-any.whl |
Total release size: 50.3 kB
Release files / eiondb-0.1.4.tar.gz
| Download URL | eiondb-0.1.4.tar.gz |
|---|---|
| Size | 27.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
444286b4675bb5ac7e862b812449f432dd4f433646f14ddc12f9d46f3672f43c
|
|
BLAKE2b-256 checksum How to use checksums |
542fbc1b01ab7638e5fc09908083be798ccfe55e52b42c07d8df8c65d705f62a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Release files / eiondb-0.1.4-py3-none-any.whl
| Download URL | eiondb-0.1.4-py3-none-any.whl |
|---|---|
| Size | 22.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5b60c669662cf82b7f9d155338ad1c8844ce3ddf9745acad2ae98238af8108f
|
|
BLAKE2b-256 checksum How to use checksums |
96243f42c5fab24a7d4d1d940c7ca75b0168e851d71c95edcdec74cdd399c8fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.5
|
Security for eiondb 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.