apsimo 1.3.0__tar.gz

apsimo-1.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aevonix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apsimo-1.3.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: apsimo
+Version: 1.3.0
+Summary: Persistent identity, memory and autonomy for AI agents
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: litellm>=1.40
+Requires-Dist: pydantic>=2.6
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: pypdf<7,>=6.18.0
+Requires-Dist: psutil<8,>=7.2.2; sys_platform == "darwin"
+Provides-Extra: graph
+Requires-Dist: neo4j>=5.18; extra == "graph"
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.18; extra == "neo4j"
+Provides-Extra: vectors
+Requires-Dist: sentence-transformers>=3.0; extra == "vectors"
+Requires-Dist: pandas>=2.0; extra == "vectors"
+Requires-Dist: pyarrow>=15.0; extra == "vectors"
+Requires-Dist: lancedb>=0.10; extra == "vectors"
+Provides-Extra: hermes
+Requires-Dist: apsimo-hermes<2,>=1.3.0; extra == "hermes"
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]<2,>=1.0; extra == "mcp"
+Provides-Extra: lancedb
+Requires-Dist: lancedb>=0.6; extra == "lancedb"
+Requires-Dist: pyarrow>=14.0; extra == "lancedb"
+Requires-Dist: pandas>=2.0; extra == "lancedb"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Provides-Extra: extraction
+Requires-Dist: PyMuPDF>=1.24; extra == "extraction"
+Requires-Dist: beautifulsoup4>=4.12; extra == "extraction"
+Provides-Extra: video
+Requires-Dist: av==18.1.0; extra == "video"
+Provides-Extra: dev
+Requires-Dist: av==18.1.0; extra == "dev"
+Requires-Dist: psutil<8,>=7.2.2; extra == "dev"
+Requires-Dist: neo4j>=5.18; extra == "dev"
+Requires-Dist: sentence-transformers>=3.0; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
+Requires-Dist: pyarrow>=15.0; extra == "dev"
+Requires-Dist: lancedb>=0.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: jsonschema>=4.21; extra == "dev"
+Requires-Dist: mcp[cli]<2,>=1.0; extra == "dev"
+Dynamic: license-file
+
+# Apsimo sidecar
+
+Apsimo provides persistent source memory, relevant context and shared work for
+a personal agent using locally configured models. This package runs the sidecar
+and supplies the `apsimo` command.
+
+Native Hermes attachment also requires the companion `apsimo-hermes` package
+and an existing supported Hermes installation. The guided local setup uses one
+OpenAI-compatible chat endpoint and SQLite; graph and vector dependencies are
+optional.
+
+See the [public setup guide](https://github.com/Aevonix/Apsimo/blob/main/docs/LOCAL-HERMES-SETUP.md)
+for installation, private identity setup, supported runtime and operation.
+The [project README](https://github.com/Aevonix/Apsimo/blob/main/README.md)
+describes current capabilities and their limits. Personal configuration,
+credentials and hardware adapters belong in the private deployment.
+
+Licensed under the included MIT license. Optional dependencies retain their
+own licenses.

apsimo-1.3.0/README.md

@@ -0,0 +1,19 @@
+# Apsimo sidecar
+
+Apsimo provides persistent source memory, relevant context and shared work for
+a personal agent using locally configured models. This package runs the sidecar
+and supplies the `apsimo` command.
+
+Native Hermes attachment also requires the companion `apsimo-hermes` package
+and an existing supported Hermes installation. The guided local setup uses one
+OpenAI-compatible chat endpoint and SQLite; graph and vector dependencies are
+optional.
+
+See the [public setup guide](https://github.com/Aevonix/Apsimo/blob/main/docs/LOCAL-HERMES-SETUP.md)
+for installation, private identity setup, supported runtime and operation.
+The [project README](https://github.com/Aevonix/Apsimo/blob/main/README.md)
+describes current capabilities and their limits. Personal configuration,
+credentials and hardware adapters belong in the private deployment.
+
+Licensed under the included MIT license. Optional dependencies retain their
+own licenses.

apsimo-1.3.0/apsimo/__init__.py

@@ -0,0 +1,38 @@
+"""Apsimo cognition server for agent runtimes.
+
+A standalone FastAPI server that agent hosts (Hermes plugin, MCP harnesses,
+REST integrations) mount via the ``/v1/host`` API surface.
+"""
+
+from pathlib import Path
+import os
+from .environment import apply_environment_aliases
+
+apply_environment_aliases()
+
+try:  # single source of truth: the installed package metadata (pyproject)
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("apsimo")
+except Exception:  # editable/unbuilt checkouts without installed metadata
+    __version__ = "0.0.0+unknown"
+
+
+def get_state_dir() -> Path:
+    """Return the selected state directory without moving existing state.
+    
+    Priority:
+    1. APSIMO_STATE_DIR or legacy COLONY_STATE_DIR (explicit override)
+    2. ~/.colony/data (retained unconfigured-library compatibility default)
+
+    Guided setup selects its explicit private instance directory. This fallback
+    stays aligned with older independently configured storage readers.
+    
+    Creates the directory if it doesn't exist.
+    """
+    explicit = os.environ.get("APSIMO_STATE_DIR") or os.environ.get("COLONY_STATE_DIR")
+    if explicit:
+        path = Path(explicit)
+    else:
+        path = Path.home() / ".colony" / "data"
+    path.mkdir(parents=True, exist_ok=True)
+    return path

apsimo-1.3.0/apsimo/__main__.py

@@ -0,0 +1,6 @@
+"""Run the same CLI used by the installed ``apsimo`` command."""
+from apsimo.cli import main
+
+
+if __name__ == "__main__":
+    main()

apsimo-1.3.0/apsimo/agent/__init__.py

@@ -0,0 +1,6 @@
+"""Colony Agent SDK — Python client for remote agents."""
+
+from .client import AgentClient
+from .models import AgentConfig, NodeCertificate
+
+__all__ = ["AgentClient", "AgentConfig", "NodeCertificate"]

apsimo-1.3.0/apsimo/agent/client.py

@@ -0,0 +1,276 @@
+"""Colony Agent Client — WebSocket client for remote agents.
+
+Usage:
+    from colony.agent import AgentClient
+
+    client = AgentClient(config_path="~/.colony/agent.json")
+
+    @client.on_initiative
+    async def handle_initiative(initiative):
+        print(f"Received: {initiative['description']}")
+        await client.acknowledge(initiative["id"])
+        result = await process_initiative(initiative)
+        await client.complete(initiative["id"], result=result)
+
+    await client.start()
+"""
+
+import asyncio
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+
+import websockets
+
+from .models import AgentConfig
+
+
+class AgentClient:
+    """WebSocket client for remote Colony agents.
+
+    Handles:
+    - WebSocket connection with auth
+    - Heartbeat loop
+    - Initiative delivery
+    - Reconnection with exponential backoff
+    """
+
+    def __init__(
+        self,
+        config_path: str = "~/.colony/agent.json",
+        config: Optional[AgentConfig] = None,
+    ) -> None:
+        """Initialize agent client.
+
+        Args:
+            config_path: Path to agent config file
+            config: Optional pre-loaded config (skips file read)
+        """
+        if config:
+            self.config = config
+        else:
+            config_file = Path(config_path).expanduser()
+            if not config_file.exists():
+                raise FileNotFoundError(f"Agent config not found: {config_file}")
+            self.config = AgentConfig.parse_file(config_file)
+
+        self._ws: Optional[websockets.WebSocketClientProtocol] = None
+        self._running = False
+        self._seq = 0
+        self._pending_acks: Dict[int, asyncio.Future] = {}
+        self._handlers: Dict[str, Callable] = {
+            "initiative": None,
+            "config": None,
+            "disconnect": None,
+        }
+
+        # Reconnection state
+        self._reconnect_delay = 1.0
+        self._max_reconnect_delay = 60.0
+
+    def on_initiative(self, handler: Callable) -> Callable:
+        """Register initiative handler."""
+        self._handlers["initiative"] = handler
+        return handler
+
+    def on_config(self, handler: Callable) -> Callable:
+        """Register config update handler."""
+        self._handlers["config"] = handler
+        return handler
+
+    def on_disconnect(self, handler: Callable) -> Callable:
+        """Register disconnect handler."""
+        self._handlers["disconnect"] = handler
+        return handler
+
+    async def start(self) -> None:
+        """Connect to Colony and start message loop."""
+        if not self.config.websocket_url:
+            raise ValueError("No websocket_url in config (local mode?)")
+
+        self._running = True
+
+        while self._running:
+            try:
+                await self._connect()
+                await self._message_loop()
+            except Exception as e:
+                if not self._running:
+                    break
+                print(f"Connection error: {e}, reconnecting in {self._reconnect_delay}s...")
+                await asyncio.sleep(self._reconnect_delay)
+                self._reconnect_delay = min(
+                    self._reconnect_delay * 2,
+                    self._max_reconnect_delay,
+                )
+
+    async def stop(self) -> None:
+        """Disconnect from Colony."""
+        self._running = False
+        if self._ws:
+            await self._ws.close()
+
+    async def _connect(self) -> None:
+        """Establish WebSocket connection with auth."""
+        headers = {}
+        if self.config.node_cert:
+            # Sign challenge with node cert
+            headers["Authorization"] = f"Bearer {self.config.node_cert.signature}"
+        headers["X-Agent-Id"] = self.config.agent_id
+
+        self._ws = await websockets.connect(
+            self.config.websocket_url,
+            extra_headers=headers,
+            ping_interval=30,
+            ping_timeout=10,
+        )
+        self._reconnect_delay = 1.0  # Reset on successful connection
+        print(f"Connected to Colony: {self.config.websocket_url}")
+
+        # Start heartbeat task
+        asyncio.create_task(self._heartbeat_loop())
+
+    async def _message_loop(self) -> None:
+        """Process incoming messages."""
+        if not self._ws:
+            return
+
+        async for message in self._ws:
+            try:
+                data = json.loads(message)
+                await self._handle_message(data)
+            except json.JSONDecodeError:
+                print(f"Invalid JSON: {message}")
+            except Exception as e:
+                print(f"Error handling message: {e}")
+
+    async def _handle_message(self, data: Dict[str, Any]) -> None:
+        """Handle incoming message."""
+        msg_type = data.get("type")
+        seq = data.get("seq")
+
+        # Handle ACKs for our messages
+        if msg_type == "ack" and seq in self._pending_acks:
+            self._pending_acks[seq].set_result(data)
+            return
+
+        # Handle initiative delivery
+        if msg_type == "initiative":
+            if self._handlers["initiative"]:
+                await self._handlers["initiative"](data.get("initiative", {}))
+            # Auto-ack receipt
+            await self._send_ack(seq)
+
+        # Handle config update
+        elif msg_type == "config":
+            if self._handlers["config"]:
+                await self._handlers["config"](data.get("config", {}))
+
+        # Handle disconnect notice
+        elif msg_type == "disconnect":
+            if self._handlers["disconnect"]:
+                await self._handlers["disconnect"](data.get("reason", "unknown"))
+            await self.stop()
+
+        # Handle ping
+        elif msg_type == "ping":
+            await self._send({"type": "pong", "seq": seq})
+
+    async def _heartbeat_loop(self) -> None:
+        """Send periodic heartbeats."""
+        # The colony side tracks current_assignments via the agents table
+        # (incremented/decremented when initiatives are assigned/completed),
+        # so the heartbeat does not need to carry it — the server only uses
+        # this message to update last_seen_at.
+        while self._running and self._ws:
+            try:
+                await self._send({
+                    "type": "heartbeat",
+                    "status": "online",
+                })
+                await asyncio.sleep(30)
+            except Exception:
+                break
+
+    async def _send(self, message: Dict[str, Any]) -> bool:
+        """Send message with sequencing."""
+        if not self._ws:
+            return False
+
+        self._seq += 1
+        message["seq"] = self._seq
+
+        try:
+            await self._ws.send(json.dumps(message))
+            return True
+        except Exception as e:
+            print(f"Send error: {e}")
+            return False
+
+    async def _send_ack(self, seq: Optional[int]) -> None:
+        """Send acknowledgment."""
+        await self._send({"type": "ack", "ack_seq": seq})
+
+    # --- Public API ---
+
+    async def acknowledge(self, initiative_id: str) -> bool:
+        """Acknowledge initiative receipt."""
+        return await self._send({
+            "type": "initiative_ack",
+            "initiative_id": initiative_id,
+        })
+
+    async def complete(
+        self,
+        initiative_id: str,
+        result: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> bool:
+        """Mark initiative as completed."""
+        return await self._send({
+            "type": "initiative_complete",
+            "initiative_id": initiative_id,
+            "result": result,
+            "result_metadata": metadata or {},
+        })
+
+    async def fail(
+        self,
+        initiative_id: str,
+        reason: str,
+        retry: bool = True,
+    ) -> bool:
+        """Mark initiative as failed."""
+        return await self._send({
+            "type": "initiative_fail",
+            "initiative_id": initiative_id,
+            "reason": reason,
+            "retry": retry,
+        })
+
+    async def delegate(
+        self,
+        initiative_id: str,
+        reason: str,
+        target_agent_id: Optional[str] = None,
+    ) -> bool:
+        """Delegate initiative to another agent."""
+        return await self._send({
+            "type": "initiative_delegate",
+            "initiative_id": initiative_id,
+            "reason": reason,
+            "target_agent_id": target_agent_id,
+        })
+
+    async def update_status(
+        self,
+        status: str = "online",
+        current_assignments: int = 0,
+    ) -> bool:
+        """Update agent status."""
+        return await self._send({
+            "type": "status_update",
+            "status": status,
+            "current_assignments": current_assignments,
+        })

apsimo-1.3.0/apsimo/agent/models.py

@@ -0,0 +1,46 @@
+"""Agent SDK models."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class NodeCertificate(BaseModel):
+    """Node certificate structure."""
+
+    colony_id: str
+    node_id: str
+    public_key: Optional[str] = None  # node_public_key_ed25519 in spec
+    issued_at: str  # ISO timestamp
+    expires_at: Optional[str] = None  # ISO timestamp
+    signature: str
+
+
+class AgentConfig(BaseModel):
+    """Agent configuration file schema.
+
+    This is the structure saved to ~/.colony/agent.json after
+    running `colony agent connect`.
+    """
+
+    agent_id: str
+    node_id: str
+    colony_id: str
+    websocket_url: Optional[str] = None  # For remote mode
+    name: str
+    capabilities: List[str] = Field(default_factory=list)
+    is_primary: bool = False
+    max_concurrent: int = 5
+    node_cert: Optional[NodeCertificate] = None
+    connection_mode: str = "remote"
+    registered_at: Optional[str] = None  # ISO timestamp
+
+    # Optional fields
+    priority: int = 1
+    excluded_types: List[str] = Field(default_factory=list)
+    included_types: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        extra = "allow"  # Forward compatibility

apsimo-1.3.0/apsimo/agents/__init__.py

@@ -0,0 +1,20 @@
+"""Multi-agent support for Colony.
+
+Provides:
+- AgentStore: Registry of connected agents
+- InviteStore: Setup code management
+- WebSocketManager: Remote agent connections
+"""
+
+from .models import Agent, AgentStatus, AgentMetadata
+from .store import AgentStore, InviteStore
+from .websocket import WebSocketManager
+
+__all__ = [
+    "Agent",
+    "AgentStatus",
+    "AgentMetadata",
+    "AgentStore",
+    "InviteStore",
+    "WebSocketManager",
+]