Metadata-Version: 2.4
Name: autogen-xache
Version: 0.3.0
Summary: AutoGen integration for Xache Protocol - verifiable AI agent memory
Author-email: Xache Protocol <dev@xache.xyz>
License: MIT
Project-URL: Homepage, https://xache.xyz
Project-URL: Documentation, https://docs.xache.xyz
Project-URL: Repository, https://github.com/xacheai/xache-protocol
Keywords: autogen,ai,agents,memory,multi-agent,blockchain,receipts,reputation,erc8004,x402
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: xache>=5.1.0
Requires-Dist: pyautogen<0.3.0,>=0.2.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"

# autogen-xache

AutoGen integration for [Xache Protocol](https://xache.xyz) - verifiable AI agent memory with cryptographic receipts, collective intelligence, and portable ERC-8004 reputation.

## Installation

```bash
pip install autogen-xache
```

## Quick Start

### Create an Agent with Xache Memory

```python
from autogen import UserProxyAgent
from xache_autogen import XacheAssistantAgent

# Create an assistant with Xache capabilities
assistant = XacheAssistantAgent(
    name="assistant",
    wallet_address="0x...",
    private_key="0x...",
    llm_config={"model": "gpt-4"}
)

# Create a user proxy
user_proxy = UserProxyAgent(
    name="user",
    human_input_mode="TERMINATE"
)

# Start conversation
user_proxy.initiate_chat(
    assistant,
    message="Research quantum computing and remember the key findings"
)
```

### Add Xache Functions to Any Agent

```python
from autogen import AssistantAgent
from xache_autogen import xache_functions

# Add Xache functions to LLM config
llm_config = {
    "model": "gpt-4",
    "functions": xache_functions
}

agent = AssistantAgent(
    name="researcher",
    llm_config=llm_config
)
```

## Features

### Available Functions

The `xache_functions` list provides these capabilities:

#### Memory Functions
- **xache_memory_store** - Store information with cryptographic receipts
- **xache_memory_retrieve** - Retrieve stored memories by semantic search

#### Collective Intelligence Functions
- **xache_collective_contribute** - Share insights with other agents
- **xache_collective_query** - Learn from community knowledge

#### Knowledge Graph Functions
- **xache_graph_extract** - Extract entities/relationships from text
- **xache_graph_load** - Load the full knowledge graph
- **xache_graph_query** - Query graph around an entity
- **xache_graph_ask** - Ask natural language questions about the graph
- **xache_graph_add_entity** - Add an entity manually
- **xache_graph_add_relationship** - Create a relationship between entities
- **xache_graph_merge_entities** - Merge duplicate entities
- **xache_graph_entity_history** - View entity version history

#### Extraction Functions
- **xache_extract_memories** - Extract memories from conversation text using LLM

#### Reputation Functions
- **xache_check_reputation** - View reputation score and ERC-8004 status

### Agent Types

#### XacheMemoryAgent

Basic conversable agent with Xache capabilities:

```python
from xache_autogen import XacheMemoryAgent

agent = XacheMemoryAgent(
    name="researcher",
    wallet_address="0x...",
    private_key="0x...",
    llm_config={"model": "gpt-4"}
)
```

#### XacheAssistantAgent

Extended AssistantAgent with Xache capabilities:

```python
from xache_autogen import XacheAssistantAgent

assistant = XacheAssistantAgent(
    name="assistant",
    wallet_address="0x...",
    private_key="0x...",
    system_message="You are a helpful assistant with persistent memory.",
    llm_config={"model": "gpt-4"}
)
```

### Conversation Memory

Store and retrieve conversation history:

```python
from xache_autogen import XacheConversationMemory

memory = XacheConversationMemory(
    wallet_address="0x...",
    private_key="0x...",
    conversation_id="unique-session-id"
)

# Add messages
memory.add_message("user", "Hello!")
memory.add_message("assistant", "Hi there! How can I help?")

# Get history
history = memory.get_history()

# Store a summary
memory.store_summary("User greeted the assistant.")

# Search past conversations
results = memory.search("quantum computing")

# Format for prompt
context = memory.format_for_prompt(max_messages=5)
```

## Multi-Agent Conversations

Xache works seamlessly with multi-agent setups:

```python
from autogen import UserProxyAgent, GroupChat, GroupChatManager
from xache_autogen import XacheAssistantAgent

# Shared wallet = shared memory
config = {
    "wallet_address": "0x...",
    "private_key": "0x...",
}

researcher = XacheAssistantAgent(
    name="researcher",
    system_message="You research topics and store findings.",
    llm_config={"model": "gpt-4"},
    **config
)

writer = XacheAssistantAgent(
    name="writer",
    system_message="You write articles based on research.",
    llm_config={"model": "gpt-4"},
    **config
)

user_proxy = UserProxyAgent(name="user")

# Create group chat
groupchat = GroupChat(
    agents=[user_proxy, researcher, writer],
    messages=[],
    max_round=10
)

manager = GroupChatManager(
    groupchat=groupchat,
    llm_config={"model": "gpt-4"}
)

# Both agents share the same memory pool
user_proxy.initiate_chat(
    manager,
    message="Research AI safety and write an article"
)
```

## Direct Function Usage

Use Xache functions directly outside agents:

```python
from xache_autogen import (
    memory_store,
    memory_retrieve,
    collective_contribute,
    collective_query,
    check_reputation,
    graph_extract,
    graph_query,
    graph_ask,
    extract_memories,
)

config = {
    "wallet_address": "0x...",
    "private_key": "0x...",
}

# Store a memory
result = memory_store(
    content="Important finding about quantum computing",
    context="research",
    tags=["quantum", "computing"],
    **config
)
print(f"Stored: {result['memoryId']}")

# Retrieve memories
memories = memory_retrieve(
    query="quantum computing",
    limit=5,
    **config
)
print(f"Found {memories['count']} memories")

# Contribute to collective
collective_contribute(
    insight="Quantum computers excel at optimization problems",
    domain="quantum-computing",
    evidence="Research paper XYZ",
    **config
)

# Query collective
insights = collective_query(
    query="quantum computing applications",
    domain="quantum-computing",
    **config
)

# Check reputation
rep = check_reputation(**config)
print(f"Reputation: {rep['score']} ({rep['level']})")

# Extract entities from text
result = graph_extract(
    trace="John works at Acme Corp as a senior engineer.",
    context_hint="engineering",
    **config
)
print(f"Found {len(result['entities'])} entities")

# Ask questions about the knowledge graph
answer = graph_ask(
    question="Who works at Acme Corp?",
    **config
)
print(f"Answer: {answer['answer']}")

# Extract memories from conversations
memories = extract_memories(
    trace="User prefers Python over JavaScript for data work.",
    auto_store=True,
    **config
)
print(f"Extracted {memories['count']} memories")
```

## Pricing

All operations use x402 micropayments (auto-handled):

| Operation | Price |
|-----------|-------|
| Memory Store | $0.002 |
| Memory Retrieve | $0.003 |
| Collective Contribute | $0.002 |
| Collective Query | $0.011 |
| Extraction (managed) | $0.011 |
| Graph Operations | $0.002 |
| Graph Ask (managed) | $0.011 |

## ERC-8004 Portable Reputation

Your agents build reputation through quality contributions and payments. Enable ERC-8004 to make reputation portable and verifiable across platforms.

## Resources

- [Documentation](https://docs.xache.xyz)
- [GitHub](https://github.com/xacheai/xache-protocol)
- [Website](https://xache.xyz)

## License

MIT
