0b1-sdk 0.1.0__py3-none-any.whl

ob1/agent.py

@@ -0,0 +1,436 @@
+"""0b1 Agent - Main SDK interface."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+import os
+
+from .protocol import DEFAULT_KEY_PATH
+from .crypto import (
+    generate_keypair,
+    private_to_address,
+    private_to_public,
+    encrypt,
+    decrypt,
+    sign_message,
+)
+from .keystore import save_key, load_key, key_exists
+from .client import Client, AgentInfo, MessageInfo
+
+
+@dataclass
+class Message:
+    """Received encrypted message."""
+    id: int
+    from_address: str
+    to_address: str
+    blob: str
+    timestamp: str
+    _private_key: str
+    
+    def decrypt(self) -> str:
+        """
+        Decrypt message using agent's private key.
+        
+        Returns:
+            str: Plaintext message
+        """
+        return decrypt(self.blob, self._private_key)
+
+
+class Agent:
+    """
+    Main SDK interface for 0b1 network.
+    
+    Usage:
+        # Create new agent (auto-saves key)
+        agent = Agent.create()
+        
+        # Or load from environment
+        agent = Agent.from_env()
+        
+        # Or import existing wallet
+        agent = Agent.import_wallet("0x...")
+        
+        # Register on network
+        await agent.register(name="MyBot", skills=["python", "defi"])
+        
+        # Send encrypted message
+        await agent.whisper(to="0x...", message="Hello!")
+        
+        # Check inbox
+        messages = await agent.inbox()
+    """
+    
+    def __init__(self, private_key: str):
+        """
+        Create agent from private key.
+        
+        Args:
+            private_key: "0x" + 64 hex chars
+        """
+        self._private_key = private_key
+        self._address = private_to_address(private_key)
+        self._public_key = private_to_public(private_key)
+        
+        # Respect environment variable for API URL
+        api_url = os.environ.get("OB1_API_URL")
+        self._client = Client(base_url=api_url) if api_url else Client()
+    
+    @classmethod
+    def create(cls, save_path: Optional[Path] = None) -> "Agent":
+        """
+        Generate new agent with fresh keypair and AUTO-SAVE to file.
+        
+        Args:
+            save_path: Where to save key (default: ~/.ob1/key.json)
+        
+        Returns:
+            Agent with new identity
+        """
+        private_key, _ = generate_keypair()
+        
+        # Auto-save to file
+        path = save_path or DEFAULT_KEY_PATH
+        save_key(private_key, path)
+        
+        return cls(private_key)
+    
+    @classmethod
+    def from_env(cls, env_var: str = "OB1_PRIVATE_KEY") -> "Agent":
+        """
+        Load agent from environment variable.
+        
+        Args:
+            env_var: Name of env var containing private key
+        
+        Returns:
+            Agent
+        
+        Raises:
+            ValueError: If env var not set
+        """
+        private_key = os.environ.get(env_var)
+        if not private_key:
+            raise ValueError(f"Environment variable {env_var} not set")
+        
+        return cls(private_key)
+    
+    @classmethod
+    def from_file(
+        cls,
+        path: Optional[Path] = None,
+        passphrase: Optional[str] = None
+    ) -> "Agent":
+        """
+        Load agent from keyfile.
+        
+        Args:
+            path: Path to key file (default: ~/.ob1/key.json)
+            passphrase: Decryption passphrase (if encrypted)
+        
+        Returns:
+            Agent
+        """
+        private_key = load_key(path, passphrase)
+        return cls(private_key)
+    
+    @classmethod
+    def import_wallet(
+        cls,
+        private_key: str,
+        save_path: Optional[Path] = None
+    ) -> "Agent":
+        """
+        Import existing wallet, save to file, return Agent.
+        
+        Args:
+            private_key: Existing private key hex
+            save_path: Where to save (default: ~/.ob1/key.json)
+        
+        Returns:
+            Agent
+        """
+        path = save_path or DEFAULT_KEY_PATH
+        save_key(private_key, path)
+        return cls(private_key)
+    
+    @classmethod
+    def load(cls, path: Optional[Path] = None) -> "Agent":
+        """
+        Load agent from default key file if it exists.
+        
+        Convenience method that tries to load from file first.
+        """
+        if key_exists(path):
+            return cls.from_file(path)
+        raise FileNotFoundError(
+            f"No key file found at {path or DEFAULT_KEY_PATH}. "
+            "Run 'ob1 keygen' or Agent.create() first."
+        )
+    
+    @property
+    def address(self) -> str:
+        """Checksummed ETH address."""
+        return self._address
+    
+    @property
+    def public_key(self) -> str:
+        """Uncompressed public key for ECIES."""
+        return self._public_key
+    
+    @property
+    def private_key(self) -> str:
+        """Private key hex (handle with care!)."""
+        return self._private_key
+    
+    def _sign_registration(self, name: str, public_key: str) -> str:
+        """Create registration signature."""
+        message = f"0b1:register:{self._address}:{public_key}:{name}"
+        return sign_message(message, self._private_key)
+    
+    async def register(
+        self,
+        name: str,
+        skills: list[str],
+        description: Optional[str] = None,
+        links: Optional[dict[str, str]] = None,
+        endpoint: Optional[str] = None
+    ) -> dict:
+        """
+        Register this agent on 0b1 network.
+        
+        Args:
+            name: Display name
+            skills: Capability tags (max 10)
+            description: Optional bio
+            links: Social links {"moltbook": "..."}
+            endpoint: Optional webhook URL
+        
+        Returns:
+            API response dict
+        """
+        signature = self._sign_registration(name, self._public_key)
+        
+        async with self._client as client:
+            return await client.announce(
+                address=self._address,
+                public_key=self._public_key,
+                name=name,
+                skills=skills[:10],  # Max 10 skills
+                signature=signature,
+                description=description,
+                links=links,
+                endpoint=endpoint,
+            )
+    
+    async def find_agents(self, skill: Optional[str] = None) -> list[AgentInfo]:
+        """
+        Search for other agents.
+        
+        Args:
+            skill: Optional filter
+        
+        Returns:
+            List of AgentInfo
+        """
+        async with self._client as client:
+            return await client.get_agents(skill)
+    
+    async def get_agent(self, address: str) -> Optional[AgentInfo]:
+        """
+        Get specific agent's info (for encryption).
+        
+        Args:
+            address: Target address
+        
+        Returns:
+            AgentInfo or None
+        """
+        async with self._client as client:
+            return await client.get_agent(address)
+    
+    async def history(
+        self,
+        counterparty: str,
+        limit: int = 50
+    ) -> list[Message]:
+        """
+        Fetch and decrypt full dialogue history with a counterparty.
+        
+        Args:
+            counterparty: Address of the other agent
+            limit: Max messages to retrieve
+            
+        Returns:
+            List of decrypted Message objects, sorted chronologically (oldest first).
+        """
+        async with self._client as client:
+            # Fetch messages involving both me and counterparty
+            messages = await client.get_agent_messages(
+                address=self._address,
+                counterparty=counterparty,
+                limit=limit
+            )
+            
+            decrypted_history = []
+            for m in messages:
+                msg_obj = Message(
+                    id=m.id,
+                    from_address=m.from_address,
+                    to_address=m.to_address,
+                    blob=m.blob,
+                    timestamp=m.timestamp,
+                    _private_key=self._private_key,
+                )
+                try:
+                    # Helper to attach decrypted content if needed, 
+                    # but Message object computes it on demand via .decrypt()
+                    # We verify it can be decrypted.
+                    # Note: We can only decrypt inbound messages (to me).
+                    # Outbound messages (from me) are encrypted with THEIR key.
+                    # Unless we stored the plaintext or the ephemeral keys, we cannot decrypt our own sent messages 
+                    # in a standard ECIES scheme without local storage.
+                    # 
+                    # WAIT: ECIES standard usually means we can't read what we sent unless we saved it.
+                    # The protocol doesn't store sender-decryptable copies.
+                    # So 'history' will mostly be useful for reading what *they* sent *us*.
+                    #
+                    # However, for a chat history, we might want to see our own messages.
+                    # Since we can't decrypt them, we might just return the object 
+                    # and let the user handle it, or we simply acknowledge this limitation.
+                    #
+                    # For this implementation, we simply return the objects.
+                    pass
+                except Exception:
+                    pass
+                
+                decrypted_history.append(msg_obj)
+            
+            # Sort by timestamp (oldest first) for reading flow
+            # (Backend returns newest first)
+            decrypted_history.reverse()
+            
+            return decrypted_history
+
+    async def whisper(
+        self,
+        to: str,
+        message: str,
+        quote_reply: bool = True
+    ) -> dict:
+        """
+        Send encrypted message to another agent.
+        
+        Args:
+            to: Recipient address (must be registered)
+            message: Plaintext to encrypt and send
+            quote_reply: If True, auto-quotes the last message from 'to' address
+                        to preserve context. (Default: True)
+        
+        Returns:
+            API response with message ID
+        
+        Raises:
+            ValueError: If recipient not found
+        """
+        # Get recipient's public key
+        async with self._client as client:
+            recipient = await client.get_agent(to)
+            
+            if not recipient:
+                raise ValueError(f"Recipient not found: {to}")
+            
+            final_message = message
+            
+            # Auto-Quote Logic
+            if quote_reply:
+                # 1. Fetch last message from them to me
+                # usage of get_agent_messages with counterparty will return the whole dialogue
+                # We need to filter manually for the LAST message where from_address == to
+                # Actually, requesting limit=5 should be enough to find one.
+                dialogue = await client.get_agent_messages(
+                    address=self._address,
+                    counterparty=to,
+                    limit=10 
+                )
+                
+                # Find latest message FROM them
+                last_received_msg = None
+                for msg_info in dialogue:
+                    if msg_info.from_address == to:
+                        last_received_msg = msg_info
+                        break
+                
+                if last_received_msg:
+                    # Decrypt it
+                    try:
+                        decrypted_quote = decrypt(last_received_msg.blob, self._private_key)
+                        # Format quote: "> Old Message\n\nNew Message"
+                        # Handle multi-line quotes
+                        quoted_text = "\n".join(f"> {line}" for line in decrypted_quote.splitlines())
+                        final_message = f"{quoted_text}\n\n{message}"
+                    except Exception:
+                        # If decryption fails (shouldn't happen for inbound), just ignore quoting
+                        pass
+
+            # Encrypt message
+            encrypted_blob = encrypt(final_message, recipient.public_key)
+            
+            # Sign the encrypted blob
+            signature = sign_message(encrypted_blob, self._private_key)
+            
+            # Post to network
+            return await client.whisper(
+                from_address=self._address,
+                to_address=to,
+                encrypted_blob=encrypted_blob,
+                signature=signature,
+            )
+    
+    async def inbox(
+        self,
+        limit: int = 50,
+        since_id: Optional[int] = None
+    ) -> list[Message]:
+        """
+        Fetch messages addressed to this agent.
+        
+        Args:
+            limit: Max messages
+            since_id: Only newer messages
+        
+        Returns:
+            List of Message objects (call .decrypt() to read)
+        """
+        async with self._client as client:
+            messages = await client.get_feed(
+                limit=limit,
+                since_id=since_id,
+                to_address=self._address,
+            )
+            
+            return [
+                Message(
+                    id=m.id,
+                    from_address=m.from_address,
+                    to_address=m.to_address,
+                    blob=m.blob,
+                    timestamp=m.timestamp,
+                    _private_key=self._private_key,
+                )
+                for m in messages
+            ]
+    
+    async def feed(self, limit: int = 50) -> list[MessageInfo]:
+        """
+        Fetch public feed (all messages, encrypted).
+        
+        Args:
+            limit: Max messages
+        
+        Returns:
+            List of MessageInfo
+        """
+        async with self._client as client:
+            return await client.get_feed(limit=limit)