solana-agent 31.0.0__tar.gz → 31.1.1__tar.gz

{solana_agent-31.0.0 → solana_agent-31.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: solana-agent
-Version: 31.0.0
+Version: 31.1.1
 Summary: AI Agents for Solana
 License: MIT
 Keywords: solana,solana ai,solana agent,ai,ai agent,ai agents
@@ -14,20 +14,20 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Dist: instructor (==1.10.0)
-Requires-Dist: llama-index-core (==0.13.0)
+Requires-Dist: instructor (==1.11.2)
+Requires-Dist: llama-index-core (==0.13.3)
 Requires-Dist: llama-index-embeddings-openai (==0.5.0)
-Requires-Dist: logfire (==4.2.0)
-Requires-Dist: openai (==1.99.3)
+Requires-Dist: logfire (==4.3.6)
+Requires-Dist: openai (==1.102.0)
 Requires-Dist: pillow (==11.3.0)
-Requires-Dist: pinecone (==7.3.0)
+Requires-Dist: pinecone[asyncio] (==7.3.0)
 Requires-Dist: pydantic (>=2)
-Requires-Dist: pymongo (==4.14.0)
-Requires-Dist: pypdf (==5.9.0)
+Requires-Dist: pymongo (==4.14.1)
+Requires-Dist: pypdf (==6.0.0)
 Requires-Dist: rich (>=13,<14.0)
 Requires-Dist: scrubadub (==2.0.1)
-Requires-Dist: typer (==0.16.0)
-Requires-Dist: zep-cloud (==3.1.0)
+Requires-Dist: typer (==0.17.3)
+Requires-Dist: zep-cloud (==3.4.3)
 Project-URL: Documentation, https://docs.solana-agent.com
 Project-URL: Homepage, https://solana-agent.com
 Project-URL: Repository, https://github.com/truemagic-coder/solana-agent
@@ -63,7 +63,7 @@ Build your AI agents in three lines of code!
 * Extensible Tooling
 * Autonomous Operation
 * Smart Workflows
-* Structured Outputs
+* Agentic Forms
 * Knowledge Base
 * MCP Support
 * Guardrails
@@ -112,7 +112,7 @@ Smart workflows are as easy as combining your tools and prompts.
 * Integrated Knowledge Base with semantic search and automatic PDF chunking
 * Input and output guardrails for content filtering, safety, and data sanitization
 * Generate custom images based on text prompts with storage on S3 compatible services
-* Deterministically return structured outputs
+* Deterministic agentic form filling in natural conversation
 * Combine with event-driven systems to create autonomous agents
 
 ## Stack
@@ -344,7 +344,9 @@ async for response in solana_agent.process("user123", "What is in this image? De
     print(response, end="")
 ```
 
-### Structured Outputs
+### Agentic Forms
+
+You can attach a JSON Schema to any agent in your config so it can collect structured data conversationally.
 
 ```python
 from solana_agent import SolanaAgent
@@ -355,25 +357,28 @@ config = {
     },
     "agents": [
         {
-            "name": "researcher",
-            "instructions": "You are a research expert.",
-            "specialization": "Researcher",
+            "name": "customer_support",
+            "instructions": "You provide friendly, helpful customer support responses.",
+            "specialization": "Customer inquiries",
+            "capture_name": "contact_info",
+            "capture_mode": "once",
+            "capture_schema": {
+                "type": "object",
+                "properties": {
+                    "email": { "type": "string" },
+                    "phone": { "type": "string" },
+                    "newsletter_subscribe": { "type": "boolean" }
+                },
+                "required": ["email"]
+            }
         }
-    ],
+    ]
 }
 
 solana_agent = SolanaAgent(config=config)
 
-class ResearchProposal(BaseModel):
-    title: str
-    abstract: str
-    key_points: list[str]
-
-full_response = None
-async for response in solana_agent.process("user123", "Research the life of Ben Franklin - the founding Father.", output_model=ResearchProposal):
-    full_response = response
-
-print(full_response.model_dump())
+async for response in solana_agent.process("user123", "What are the latest AI developments?"):
+    print(response, end="")
 ```
 
 ### Command Line Interface (CLI)

{solana_agent-31.0.0 → solana_agent-31.1.1}/README.md

@@ -28,7 +28,7 @@ Build your AI agents in three lines of code!
 * Extensible Tooling
 * Autonomous Operation
 * Smart Workflows
-* Structured Outputs
+* Agentic Forms
 * Knowledge Base
 * MCP Support
 * Guardrails
@@ -77,7 +77,7 @@ Smart workflows are as easy as combining your tools and prompts.
 * Integrated Knowledge Base with semantic search and automatic PDF chunking
 * Input and output guardrails for content filtering, safety, and data sanitization
 * Generate custom images based on text prompts with storage on S3 compatible services
-* Deterministically return structured outputs
+* Deterministic agentic form filling in natural conversation
 * Combine with event-driven systems to create autonomous agents
 
 ## Stack
@@ -309,7 +309,9 @@ async for response in solana_agent.process("user123", "What is in this image? De
     print(response, end="")
 ```
 
-### Structured Outputs
+### Agentic Forms
+
+You can attach a JSON Schema to any agent in your config so it can collect structured data conversationally.
 
 ```python
 from solana_agent import SolanaAgent
@@ -320,25 +322,28 @@ config = {
     },
     "agents": [
         {
-            "name": "researcher",
-            "instructions": "You are a research expert.",
-            "specialization": "Researcher",
+            "name": "customer_support",
+            "instructions": "You provide friendly, helpful customer support responses.",
+            "specialization": "Customer inquiries",
+            "capture_name": "contact_info",
+            "capture_mode": "once",
+            "capture_schema": {
+                "type": "object",
+                "properties": {
+                    "email": { "type": "string" },
+                    "phone": { "type": "string" },
+                    "newsletter_subscribe": { "type": "boolean" }
+                },
+                "required": ["email"]
+            }
         }
-    ],
+    ]
 }
 
 solana_agent = SolanaAgent(config=config)
 
-class ResearchProposal(BaseModel):
-    title: str
-    abstract: str
-    key_points: list[str]
-
-full_response = None
-async for response in solana_agent.process("user123", "Research the life of Ben Franklin - the founding Father.", output_model=ResearchProposal):
-    full_response = response
-
-print(full_response.model_dump())
+async for response in solana_agent.process("user123", "What are the latest AI developments?"):
+    print(response, end="")
 ```
 
 ### Command Line Interface (CLI)

{solana_agent-31.0.0 → solana_agent-31.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "31.0.0"
+version = "31.1.1"
 description = "AI Agents for Solana"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -19,23 +19,23 @@ classifiers = [
 ]
 packages = [{ include = "solana_agent" }]
 
-[tool.pytest.ini-options]
-python_paths = [".", "tests"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]
 
 [tool.poetry.dependencies]
 python = ">=3.12,<4.0"
-openai = "1.99.3"
+openai = "1.102.0"
 pydantic = ">=2"
-pymongo = "4.14.0"
-zep-cloud = "3.1.0"
-instructor = "1.10.0"
-pinecone = "7.3.0"
-llama-index-core = "0.13.0"
+pymongo = "4.14.1"
+zep-cloud = "3.4.3"
+instructor = "1.11.2"
+pinecone = { version = "7.3.0", extras = ["asyncio"] }
+llama-index-core = "0.13.3"
 llama-index-embeddings-openai = "0.5.0"
-pypdf = "5.9.0"
+pypdf = "6.0.0"
 scrubadub = "2.0.1"
-logfire = "4.2.0"
-typer = "0.16.0"
+logfire = "4.3.6"
+typer = "0.17.3"
 rich = ">=13,<14.0"
 pillow = "11.3.0"
 
@@ -50,7 +50,7 @@ sphinx-rtd-theme = "^3.0.2"
 myst-parser = "^4.0.1"
 sphinx-autobuild = "^2024.10.3"
 mongomock = "^4.3.0"
-ruff = "^0.12.8"
+ruff = "^0.12.10"
 
 [tool.poetry.scripts]
 solana-agent = "solana_agent.cli:app"

{solana_agent-31.0.0 → solana_agent-31.1.1}/solana_agent/client/solana_agent.py

@@ -49,6 +49,8 @@ class SolanaAgent(SolanaAgentInterface):
         user_id: str,
         message: Union[str, bytes],
         prompt: Optional[str] = None,
+        capture_schema: Optional[Dict[str, Any]] = None,
+        capture_name: Optional[str] = None,
         output_format: Literal["text", "audio"] = "text",
         audio_voice: Literal[
             "alloy",
@@ -103,6 +105,8 @@ class SolanaAgent(SolanaAgentInterface):
             prompt=prompt,
             router=router,
             output_model=output_model,
+            capture_schema=capture_schema,
+            capture_name=capture_name,
         ):
             yield chunk
 

{solana_agent-31.0.0 → solana_agent-31.1.1}/solana_agent/domains/agent.py

@@ -5,7 +5,7 @@ This module defines the core domain models for representing
 AI agents, human agents, and business mission/values.
 """
 
-from typing import List, Dict
+from typing import List, Dict, Optional, Any
 from pydantic import BaseModel, Field, field_validator
 
 
@@ -53,6 +53,12 @@ class AIAgent(BaseModel):
     name: str = Field(..., description="Unique agent identifier name")
     instructions: str = Field(..., description="Base instructions for the agent")
     specialization: str = Field(..., description="Agent's specialized domain")
+    capture_name: Optional[str] = Field(
+        default=None, description="Optional capture name for structured data"
+    )
+    capture_schema: Optional[Dict[str, Any]] = Field(
+        default=None, description="Optional JSON schema for structured capture"
+    )
 
     @field_validator("name", "specialization")
     @classmethod

{solana_agent-31.0.0 → solana_agent-31.1.1}/solana_agent/factories/agent_factory.py

@@ -133,21 +133,38 @@ class SolanaAgentFactory:
                 voice=org_config.get("voice", ""),
             )
 
+        # Build capture modes from agent config if provided
+        capture_modes: Dict[str, str] = {}
+        for agent in config.get("agents", []):
+            mode = agent.get("capture_mode")
+            if mode in {"once", "multiple"} and agent.get("name"):
+                capture_modes[agent["name"]] = mode
+
         # Create repositories
         memory_provider = None
 
         if "zep" in config and "mongo" in config:
-            memory_provider = MemoryRepository(
-                mongo_adapter=db_adapter, zep_api_key=config["zep"].get("api_key")
-            )
+            mem_kwargs: Dict[str, Any] = {
+                "mongo_adapter": db_adapter,
+                "zep_api_key": config["zep"].get("api_key"),
+            }
+            if capture_modes:  # pragma: no cover
+                mem_kwargs["capture_modes"] = capture_modes
+            memory_provider = MemoryRepository(**mem_kwargs)
 
         if "mongo" in config and "zep" not in config:
-            memory_provider = MemoryRepository(mongo_adapter=db_adapter)
+            mem_kwargs = {"mongo_adapter": db_adapter}
+            if capture_modes:
+                mem_kwargs["capture_modes"] = capture_modes
+            memory_provider = MemoryRepository(**mem_kwargs)
 
         if "zep" in config and "mongo" not in config:
             if "api_key" not in config["zep"]:
                 raise ValueError("Zep API key is required.")
-            memory_provider = MemoryRepository(zep_api_key=config["zep"].get("api_key"))
+            mem_kwargs = {"zep_api_key": config["zep"].get("api_key")}
+            if capture_modes:  # pragma: no cover
+                mem_kwargs["capture_modes"] = capture_modes
+            memory_provider = MemoryRepository(**mem_kwargs)
 
         guardrail_config = config.get("guardrails", {})
         input_guardrails: List[InputGuardrail] = SolanaAgentFactory._create_guardrails(
@@ -169,9 +186,16 @@ class SolanaAgentFactory:
         )
 
         # Create routing service
+        # Optional routing model override (use small, cheap model by default in service)
+        routing_model = (
+            config.get("openai", {}).get("routing_model")
+            if isinstance(config.get("openai"), dict)
+            else None
+        )
         routing_service = RoutingService(
             llm_provider=llm_adapter,
             agent_service=agent_service,
+            model=routing_model,
         )
 
         # Debug the agent service tool registry
@@ -191,11 +215,18 @@ class SolanaAgentFactory:
             loaded_plugins = 0
 
         # Register predefined agents
-        for agent_config in config.get("agents", []):
+        for agent_config in config.get("agents", []):  # pragma: no cover
+            extra_kwargs = {}
+            if "capture_name" in agent_config:
+                extra_kwargs["capture_name"] = agent_config.get("capture_name")
+            if "capture_schema" in agent_config:
+                extra_kwargs["capture_schema"] = agent_config.get("capture_schema")
+
             agent_service.register_ai_agent(
                 name=agent_config["name"],
                 instructions=agent_config["instructions"],
                 specialization=agent_config["specialization"],
+                **extra_kwargs,
             )
 
             # Register tools for this agent

{solana_agent-31.0.0 → solana_agent-31.1.1}/solana_agent/interfaces/providers/memory.py

@@ -36,3 +36,15 @@ class MemoryProvider(ABC):
     def count_documents(self, collection: str, query: Dict) -> int:
         """Count documents matching query."""
         pass
+
+    @abstractmethod
+    async def save_capture(
+        self,
+        user_id: str,
+        capture_name: str,
+        agent_name: Optional[str],
+        data: Dict[str, Any],
+        schema: Optional[Dict[str, Any]] = None,
+    ) -> Optional[str]:
+        """Persist a structured capture for a user and return its ID if available."""
+        pass

{solana_agent-31.0.0 → solana_agent-31.1.1}/solana_agent/interfaces/services/query.py

@@ -38,6 +38,8 @@ class QueryService(ABC):
         router: Optional[RoutingInterface] = None,
         images: Optional[List[Union[str, bytes]]] = None,
         output_model: Optional[Type[BaseModel]] = None,
+        capture_schema: Optional[Dict[str, Any]] = None,
+        capture_name: Optional[str] = None,
     ) -> AsyncGenerator[Union[str, bytes, BaseModel], None]:
         """Process the user request and generate a response."""
         pass

solana_agent-31.1.1/solana_agent/repositories/memory.py

@@ -0,0 +1,276 @@
+import logging
+from typing import List, Dict, Optional, Tuple, Any
+from datetime import datetime, timezone
+from copy import deepcopy
+
+from zep_cloud.client import AsyncZep as AsyncZepCloud
+from zep_cloud.types import Message
+
+from solana_agent.interfaces.providers.memory import MemoryProvider
+from solana_agent.adapters.mongodb_adapter import MongoDBAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryRepository(MemoryProvider):
+    """Combined Zep and MongoDB implementation of MemoryProvider."""
+
+    def __init__(
+        self,
+        mongo_adapter: Optional[MongoDBAdapter] = None,
+        zep_api_key: Optional[str] = None,
+        capture_modes: Optional[Dict[str, str]] = None,
+    ):
+        self.capture_modes: Dict[str, str] = capture_modes or {}
+
+        # Mongo setup
+        if not mongo_adapter:
+            self.mongo = None
+            self.collection = None
+            self.captures_collection = "captures"
+        else:
+            self.mongo = mongo_adapter
+            self.collection = "conversations"
+            try:
+                self.mongo.create_collection(self.collection)
+                self.mongo.create_index(self.collection, [("user_id", 1)])
+                self.mongo.create_index(self.collection, [("timestamp", 1)])
+            except Exception as e:
+                logger.error(f"Error initializing MongoDB: {e}")
+
+            try:
+                self.captures_collection = "captures"
+                self.mongo.create_collection(self.captures_collection)
+                # Basic indexes
+                self.mongo.create_index(self.captures_collection, [("user_id", 1)])
+                self.mongo.create_index(self.captures_collection, [("capture_name", 1)])
+                self.mongo.create_index(self.captures_collection, [("agent_name", 1)])
+                self.mongo.create_index(self.captures_collection, [("timestamp", 1)])
+                # Unique only when mode == 'once'
+                try:
+                    self.mongo.create_index(
+                        self.captures_collection,
+                        [("user_id", 1), ("agent_name", 1), ("capture_name", 1)],
+                        unique=True,
+                        partialFilterExpression={"mode": "once"},
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Error creating partial unique index for captures: {e}"
+                    )
+            except Exception as e:
+                logger.error(f"Error initializing MongoDB captures collection: {e}")
+                self.captures_collection = "captures"
+
+        # Zep setup
+        self.zep = AsyncZepCloud(api_key=zep_api_key) if zep_api_key else None
+
+    async def store(self, user_id: str, messages: List[Dict[str, Any]]) -> None:
+        if not user_id or not isinstance(user_id, str):
+            raise ValueError("User ID cannot be None or empty")
+        if not messages or not isinstance(messages, list):
+            raise ValueError("Messages must be a non-empty list")
+        if not all(
+            isinstance(m, dict) and "role" in m and "content" in m for m in messages
+        ):
+            raise ValueError(
+                "All messages must be dictionaries with 'role' and 'content' keys"
+            )
+        for m in messages:
+            if m["role"] not in ["user", "assistant"]:
+                raise ValueError(
+                    "Invalid role in message. Only 'user' and 'assistant' are accepted."
+                )
+
+        # Persist last user/assistant pair to Mongo
+        if self.mongo and len(messages) >= 2:
+            try:
+                user_msg = None
+                assistant_msg = None
+                for m in reversed(messages):
+                    if m.get("role") == "user" and not user_msg:
+                        user_msg = m.get("content")
+                    elif m.get("role") == "assistant" and not assistant_msg:
+                        assistant_msg = m.get("content")
+                    if user_msg and assistant_msg:
+                        break
+                if user_msg and assistant_msg:
+                    self.mongo.insert_one(
+                        self.collection,
+                        {
+                            "user_id": user_id,
+                            "user_message": user_msg,
+                            "assistant_message": assistant_msg,
+                            "timestamp": datetime.now(timezone.utc),
+                        },
+                    )
+            except Exception as e:
+                logger.error(f"MongoDB storage error: {e}")
+
+        # Zep
+        if not self.zep:
+            return
+
+        zep_messages: List[Message] = []
+        for m in messages:
+            content = (
+                self._truncate(deepcopy(m.get("content"))) if "content" in m else None
+            )
+            if content is None:  # pragma: no cover
+                continue
+            role_type = "user" if m.get("role") == "user" else "assistant"
+            zep_messages.append(Message(content=content, role=role_type))
+
+        if zep_messages:
+            try:
+                await self.zep.thread.add_messages(
+                    thread_id=user_id, messages=zep_messages
+                )
+            except Exception:
+                try:
+                    try:
+                        await self.zep.user.add(user_id=user_id)
+                    except Exception as e:
+                        logger.error(f"Zep user addition error: {e}")
+                    try:
+                        await self.zep.thread.create(thread_id=user_id, user_id=user_id)
+                    except Exception as e:
+                        logger.error(f"Zep thread creation error: {e}")
+                    await self.zep.thread.add_messages(
+                        thread_id=user_id, messages=zep_messages
+                    )
+                except Exception as e:
+                    logger.error(f"Zep memory addition error: {e}")
+
+    async def retrieve(self, user_id: str) -> str:
+        try:
+            memories = ""
+            if self.zep:
+                memory = await self.zep.thread.get_user_context(thread_id=user_id)
+                if memory and memory.context:
+                    memories = memory.context
+            return memories
+        except Exception as e:
+            logger.error(f"Error retrieving memories: {e}")
+            return ""
+
+    async def delete(self, user_id: str) -> None:
+        if self.mongo:
+            try:
+                self.mongo.delete_all(self.collection, {"user_id": user_id})
+            except Exception as e:
+                logger.error(f"MongoDB deletion error: {e}")
+        if not self.zep:
+            return
+        try:
+            await self.zep.thread.delete(thread_id=user_id)
+        except Exception as e:
+            logger.error(f"Zep memory deletion error: {e}")
+        try:
+            await self.zep.user.delete(user_id=user_id)
+        except Exception as e:
+            logger.error(f"Zep user deletion error: {e}")
+
+    def find(
+        self,
+        collection: str,
+        query: Dict,
+        sort: Optional[List[Tuple]] = None,
+        limit: int = 0,
+        skip: int = 0,
+    ) -> List[Dict]:  # pragma: no cover
+        if not self.mongo:
+            return []
+        try:
+            return self.mongo.find(collection, query, sort=sort, limit=limit, skip=skip)
+        except Exception as e:
+            logger.error(f"MongoDB find error: {e}")
+            return []
+
+    def count_documents(self, collection: str, query: Dict) -> int:
+        if not self.mongo:
+            return 0
+        return self.mongo.count_documents(collection, query)
+
+    def _truncate(self, text: str, limit: int = 2500) -> str:
+        if text is None:
+            raise AttributeError("Cannot truncate None text")
+        if not text:
+            return ""
+        if len(text) <= limit:
+            return text
+        last_period = text.rfind(".", 0, limit)
+        if last_period > 0:
+            return text[: last_period + 1]
+        return text[: limit - 3] + "..."
+
+    async def save_capture(
+        self,
+        user_id: str,
+        capture_name: str,
+        agent_name: Optional[str],
+        data: Dict[str, Any],
+        schema: Optional[Dict[str, Any]] = None,
+    ) -> Optional[str]:
+        if not self.mongo:  # pragma: no cover
+            logger.warning("MongoDB not configured; cannot save capture.")
+            return None
+        if not user_id or not isinstance(user_id, str):
+            raise ValueError("user_id must be a non-empty string")
+        if not capture_name or not isinstance(capture_name, str):
+            raise ValueError("capture_name must be a non-empty string")
+        if not isinstance(data, dict):
+            raise ValueError("data must be a dictionary")
+
+        try:
+            mode = self.capture_modes.get(agent_name, "once") if agent_name else "once"
+            now = datetime.now(timezone.utc)
+            if mode == "multiple":
+                doc = {
+                    "user_id": user_id,
+                    "agent_name": agent_name,
+                    "capture_name": capture_name,
+                    "data": data or {},
+                    "schema": schema or {},
+                    "mode": "multiple",
+                    "timestamp": now,
+                    "created_at": now,
+                }
+                return self.mongo.insert_one(self.captures_collection, doc)
+            else:
+                key = {
+                    "user_id": user_id,
+                    "agent_name": agent_name,
+                    "capture_name": capture_name,
+                }
+                existing = self.mongo.find_one(self.captures_collection, key)
+                merged_data: Dict[str, Any] = {}
+                if existing and isinstance(existing.get("data"), dict):
+                    merged_data.update(existing.get("data", {}))
+                merged_data.update(data or {})
+                update_doc = {
+                    "$set": {
+                        "user_id": user_id,
+                        "agent_name": agent_name,
+                        "capture_name": capture_name,
+                        "data": merged_data,
+                        "schema": (
+                            schema
+                            if schema is not None
+                            else existing.get("schema")
+                            if existing
+                            else {}
+                        ),
+                        "mode": "once",
+                        "timestamp": now,
+                    },
+                    "$setOnInsert": {"created_at": now},
+                }
+                self.mongo.update_one(
+                    self.captures_collection, key, update_doc, upsert=True
+                )
+                doc = self.mongo.find_one(self.captures_collection, key)
+                return str(doc.get("_id")) if doc and doc.get("_id") else None
+        except Exception as e:  # pragma: no cover
+            logger.error(f"MongoDB save_capture error: {e}")
+            return None