Metadata-Version: 2.4
Name: maximem-synap
Version: 0.2.0
Summary: Python SDK for MaximemSynap context management system
Author: MaximemSynap Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/maximem-synap/sdk-python
Project-URL: Documentation, https://docs.synap.example.com
Project-URL: Repository, https://github.com/maximem-synap/sdk-python
Keywords: context,memory,ai,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=41.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: grpcio>=1.60.0
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Requires-Dist: pyyaml>=6.0; extra == "postgres"
Provides-Extra: vector
Requires-Dist: chromadb>=0.4.0; extra == "vector"
Requires-Dist: pyyaml>=6.0; extra == "vector"
Provides-Extra: graph
Requires-Dist: neo4j>=5.0.0; extra == "graph"
Requires-Dist: pyyaml>=6.0; extra == "graph"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# MaximemSynap Python SDK

Python client library for the MaximemSynap context management system.

## Installation

```bash
pip install maximem-synap
```

## Quick Start

```python
from maximem_synap import MaximemSynapSDK, ContextType, CompactionLevel

# Initialize SDK
sdk = MaximemSynapSDK(instance_id="your-instance-id")

# Fetch conversation context
context = sdk.conversation.fetch(
    conversation_id="conv-123",
    search_query="user preferences",
    max_results=10,
    types=[ContextType.FACTS, ContextType.PREFERENCES]
)

# Access context items
for item in context.items:
    print(f"{item.context_type}: {item.content}")

# Compact conversation context
compacted = sdk.conversation.compact(
    conversation_id="conv-123",
    compaction_level=CompactionLevel.BALANCED
)

# Fetch user context
user_context = sdk.user.fetch(
    user_id="user-456",
    conversation_id="conv-123",  # Optional
    max_results=20
)

# Listen for real-time updates
sdk.instance.listen()
# ... your application logic ...
sdk.instance.stop()

# Cleanup
sdk.shutdown()
```

## Configuration

```python
from maximem_synap import CacheConfig, TimeoutConfig

# Configure caching
cache_config = CacheConfig(
    enabled=True,
    ttl_seconds=300,
    max_entries=1000
)

# Configure timeouts
timeout_config = TimeoutConfig(
    connect_timeout_ms=5000,
    read_timeout_ms=30000,
    total_timeout_ms=60000
)

# Apply configuration
sdk.configure(
    cache=cache_config,
    log_level="DEBUG",
    timeouts=timeout_config
)
```

## Environment Variables

- `SYNAP_CLIENT_ID`: Client identifier for authentication

## Context Controllers

### Conversation Context

```python
# Fetch conversation context
context = sdk.conversation.fetch(
    conversation_id="conv-123",
    search_query="optional search",
    max_results=10,
    types=[ContextType.FACTS]
)

# Compact conversation context
compacted = sdk.conversation.compact(
    conversation_id="conv-123",
    compaction_level=CompactionLevel.ADAPTIVE
)
```

### User Context

```python
context = sdk.user.fetch(
    user_id="user-456",
    conversation_id="conv-123",  # Optional
    types=[ContextType.PREFERENCES, ContextType.EMOTIONS]
)
```

### Customer Context

```python
context = sdk.customer.fetch(
    customer_id="cust-789",
    conversation_id="conv-123"  # Optional
)
```

### Client Context

```python
context = sdk.client.fetch(
    client_id="client-abc",
    conversation_id="conv-123"  # Optional
)
```

## Error Handling

```python
from maximem_synap import (
    SDKError,
    AgentUnavailableError,
    ContextNotFoundError,
    AuthenticationError
)

try:
    context = sdk.conversation.fetch(conversation_id="conv-123")
except AgentUnavailableError as e:
    # Retryable error
    print(f"Agent unavailable: {e}")
except ContextNotFoundError as e:
    # Non-retryable error
    print(f"Context not found: {e}")
except AuthenticationError as e:
    # Authentication failed
    print(f"Auth error: {e}")
except SDKError as e:
    # Base exception
    print(f"SDK error: {e}, retryable: {e.retryable}")
```

## Context Types

- `ContextType.FACTS`: Factual information
- `ContextType.PREFERENCES`: User preferences
- `ContextType.EPISODES`: Conversation episodes
- `ContextType.EMOTIONS`: Emotional context
- `ContextType.TEMPORAL`: Time-based context
- `ContextType.ALL`: All context types

## Compaction Levels

- `CompactionLevel.AGGRESSIVE`: Maximum compression
- `CompactionLevel.BALANCED`: Balanced approach
- `CompactionLevel.CONSERVATIVE`: Minimal compression
- `CompactionLevel.ADAPTIVE`: Adaptive based on context

## License

MIT
