solana-agent 30.0.9__tar.gz → 31.1.0__tar.gz

{solana_agent-30.0.9 → solana_agent-31.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: solana-agent
-Version: 30.0.9
+Version: 31.1.0
 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.9.2)
-Requires-Dist: llama-index-core (==0.12.48)
-Requires-Dist: llama-index-embeddings-openai (==0.3.1)
-Requires-Dist: logfire (==3.23.0)
-Requires-Dist: openai (==1.93.3)
+Requires-Dist: instructor (==1.10.0)
+Requires-Dist: llama-index-core (==0.13.3)
+Requires-Dist: llama-index-embeddings-openai (==0.5.0)
+Requires-Dist: logfire (==4.3.5)
+Requires-Dist: openai (==1.101.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.13.2)
-Requires-Dist: pypdf (==5.7.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 (==2.17.0)
+Requires-Dist: typer (==0.16.1)
+Requires-Dist: zep-cloud (==3.4.1)
 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-30.0.9 → solana_agent-31.1.0}/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-30.0.9 → solana_agent-31.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "30.0.9"
+version = "31.1.0"
 description = "AI Agents for Solana"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -19,30 +19,30 @@ 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.93.3"
+openai = "1.101.0"
 pydantic = ">=2"
-pymongo = "4.13.2"
-zep-cloud = "2.17.0"
-instructor = "1.9.2"
-pinecone = "7.3.0"
-llama-index-core = "0.12.48"
-llama-index-embeddings-openai = "0.3.1"
-pypdf = "5.7.0"
+pymongo = "4.14.1"
+zep-cloud = "3.4.1"
+instructor = "1.10.0"
+pinecone = { version = "7.3.0", extras = ["asyncio"] }
+llama-index-core = "0.13.3"
+llama-index-embeddings-openai = "0.5.0"
+pypdf = "6.0.0"
 scrubadub = "2.0.1"
-logfire = "3.23.0"
-typer = "0.16.0"
+logfire = "4.3.5"
+typer = "0.16.1"
 rich = ">=13,<14.0"
 pillow = "11.3.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.4.0"
 pytest-cov = "^6.1.1"
-pytest-asyncio = "^1.0.0"
+pytest-asyncio = "^1.1.0"
 pytest-mock = "^3.14.0"
 pytest-github-actions-annotate-failures = "^0.3.0"
 sphinx = "^8.2.3"
@@ -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.2"
+ruff = "^0.12.10"
 
 [tool.poetry.scripts]
 solana-agent = "solana_agent.cli:app"

{solana_agent-30.0.9 → solana_agent-31.1.0}/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-30.0.9 → solana_agent-31.1.0}/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-30.0.9 → solana_agent-31.1.0}/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(
@@ -191,11 +208,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-30.0.9 → solana_agent-31.1.0}/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-30.0.9 → solana_agent-31.1.0}/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.0/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

{solana_agent-30.0.9 → solana_agent-31.1.0}/solana_agent/services/agent.py

@@ -73,6 +73,8 @@ class AgentService(AgentServiceInterface):
         name: str,
         instructions: str,
         specialization: str,
+        capture_name: Optional[str] = None,
+        capture_schema: Optional[Dict[str, Any]] = None,
     ) -> None:
         """Register an AI agent with its specialization.
 
@@ -85,6 +87,8 @@ class AgentService(AgentServiceInterface):
             name=name,
             instructions=instructions,
             specialization=specialization,
+            capture_name=capture_name,
+            capture_schema=capture_schema,
         )
         self.agents.append(agent)
         logger.info(f"Registered AI agent: {name}")
@@ -98,7 +102,6 @@ class AgentService(AgentServiceInterface):
         Returns:
             System prompt
         """
-
         # Get agent by name
         agent = next((a for a in self.agents if a.name == agent_name), None)
 
@@ -130,8 +133,37 @@ class AgentService(AgentServiceInterface):
                 )
                 system_prompt += f"\n\nBUSINESS GOALS:\n{goals_text}"
 
+        # Add capture guidance if this agent has a capture schema
+        if getattr(agent, "capture_schema", None) and getattr(
+            agent, "capture_name", None
+        ):  # pragma: no cover
+            system_prompt += (
+                "\n\nSTRUCTURED DATA CAPTURE:\n"
+                f"You must collect the following fields for the form '{agent.capture_name}'. "
+                "Ask concise follow-up questions to fill any missing required fields one at a time. "
+                "Confirm values when ambiguous, and summarize the captured data before finalizing.\n\n"
+                "JSON Schema (authoritative definition of the fields):\n"
+                f"{agent.capture_schema}\n\n"
+                "Rules:\n"
+                "- Never invent values—ask the user.\n"
+                "- Validate types (emails look like emails, numbers are numbers, booleans are yes/no).\n"
+                "- If the user declines to provide a required value, note it clearly.\n"
+                "- When all required fields are provided, acknowledge completion.\n"
+            )
+
         return system_prompt
 
+    def get_agent_capture(
+        self, agent_name: str
+    ) -> Optional[Dict[str, Any]]:  # pragma: no cover
+        """Return capture metadata for the agent, if any."""
+        agent = next((a for a in self.agents if a.name == agent_name), None)
+        if not agent:
+            return None
+        if agent.capture_name and agent.capture_schema:
+            return {"name": agent.capture_name, "schema": agent.capture_schema}
+        return None
+
     def get_all_ai_agents(self) -> Dict[str, AIAgent]:
         """Get all registered AI agents.
 

{solana_agent-30.0.9 → solana_agent-31.1.0}/solana_agent/services/query.py

@@ -89,6 +89,8 @@ class QueryService(QueryServiceInterface):
         prompt: Optional[str] = None,
         router: Optional[RoutingServiceInterface] = 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]:  # pragma: no cover
         """Process the user request with appropriate agent and apply input guardrails.
 
@@ -263,6 +265,47 @@ class QueryService(QueryServiceInterface):
                     )
             else:
                 full_text_response = ""
+                # If capture_schema is provided, we run a structured output pass first
+                capture_data: Optional[BaseModel] = None
+                # If no explicit capture provided, use the agent's configured capture
+                if not capture_schema or not capture_name:
+                    try:
+                        cap = self.agent_service.get_agent_capture(agent_name)
+                        if cap:
+                            capture_name = cap.get("name")
+                            capture_schema = cap.get("schema")
+                    except Exception:
+                        pass
+
+                if capture_schema and capture_name:
+                    try:
+                        # Build a dynamic Pydantic model from JSON schema
+                        DynamicModel = self._build_model_from_json_schema(
+                            capture_name, capture_schema
+                        )
+                        async for result in self.agent_service.generate_response(
+                            agent_name=agent_name,
+                            user_id=user_id,
+                            query=user_text,
+                            images=images,
+                            memory_context=combined_context,
+                            output_format="text",
+                            prompt=(
+                                (
+                                    prompt
+                                    + "\n\nReturn only the JSON for the requested schema."
+                                )
+                                if prompt
+                                else "Return only the JSON for the requested schema."
+                            ),
+                            output_model=DynamicModel,
+                        ):
+                            # This yields a pydantic model instance
+                            capture_data = result  # type: ignore
+                            break
+                    except Exception as e:
+                        logger.error(f"Error during capture structured output: {e}")
+
                 async for chunk in self.agent_service.generate_response(
                     agent_name=agent_name,
                     user_id=user_id,
@@ -286,6 +329,30 @@ class QueryService(QueryServiceInterface):
                         assistant_message=full_text_response,
                     )
 
+                # Persist capture if available
+                if (
+                    self.memory_provider
+                    and capture_schema
+                    and capture_name
+                    and capture_data is not None
+                ):
+                    try:
+                        # pydantic v2: model_dump
+                        data_dict = (
+                            capture_data.model_dump()  # type: ignore[attr-defined]
+                            if hasattr(capture_data, "model_dump")
+                            else capture_data.dict()  # type: ignore
+                        )
+                        await self.memory_provider.save_capture(
+                            user_id=user_id,
+                            capture_name=capture_name,
+                            agent_name=agent_name,
+                            data=data_dict,
+                            schema=capture_schema,
+                        )
+                    except Exception as e:
+                        logger.error(f"Error saving capture: {e}")
+
         except Exception as e:
             import traceback
 
@@ -458,3 +525,52 @@ class QueryService(QueryServiceInterface):
             logger.debug(
                 "Memory provider not configured, skipping conversation storage."
             )
+
+    def _build_model_from_json_schema(
+        self, name: str, schema: Dict[str, Any]
+    ) -> Type[BaseModel]:
+        """Create a Pydantic model dynamically from a JSON Schema subset.
+
+        Supports 'type' string, integer, number, boolean, object (flat), array (of simple types),
+        required fields, and default values. Nested objects/arrays can be extended later.
+        """
+        from pydantic import create_model
+
+        def py_type(js: Dict[str, Any]):
+            t = js.get("type")
+            if isinstance(t, list):
+                # handle ["null", "string"] => Optional[str]
+                non_null = [x for x in t if x != "null"]
+                if not non_null:
+                    return Optional[Any]
+                base = py_type({"type": non_null[0]})
+                return Optional[base]
+            if t == "string":
+                return str
+            if t == "integer":
+                return int
+            if t == "number":
+                return float
+            if t == "boolean":
+                return bool
+            if t == "array":
+                items = js.get("items", {"type": "string"})
+                return List[py_type(items)]
+            if t == "object":
+                # For now, represent as Dict[str, Any]
+                return Dict[str, Any]
+            return Any
+
+        properties: Dict[str, Any] = schema.get("properties", {})
+        required = set(schema.get("required", []))
+        fields = {}
+        for field_name, field_schema in properties.items():
+            typ = py_type(field_schema)
+            default = field_schema.get("default")
+            if field_name in required and default is None:
+                fields[field_name] = (typ, ...)
+            else:
+                fields[field_name] = (typ, default)
+
+        Model = create_model(name, **fields)  # type: ignore
+        return Model

solana_agent-30.0.9/solana_agent/repositories/memory.py

@@ -1,208 +0,0 @@
-import logging  # Import logging
-from copy import deepcopy
-from typing import List, Dict, Any, Optional, Tuple
-from datetime import datetime, timezone
-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
-
-# Setup logger for this module
-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,
-    ):
-        """Initialize the combined memory provider."""
-        if not mongo_adapter:
-            self.mongo = None
-            self.collection = None
-        else:
-            # Initialize MongoDB
-            self.mongo = mongo_adapter
-            self.collection = "conversations"
-
-            try:
-                # Ensure MongoDB collection and indexes
-                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}")  # Use logger.error
-
-        self.zep = None
-        # Initialize Zep
-        if zep_api_key:
-            self.zep = AsyncZepCloud(api_key=zep_api_key)
-
-    async def store(self, user_id: str, messages: List[Dict[str, Any]]) -> None:
-        """Store messages in both Zep and MongoDB."""
-        if not user_id:
-            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(msg, dict) and "role" in msg and "content" in msg
-            for msg in messages
-        ):
-            raise ValueError(
-                "All messages must be dictionaries with 'role' and 'content' keys"
-            )
-        for msg in messages:
-            if msg["role"] not in ["user", "assistant"]:
-                raise ValueError(
-                    f"Invalid role '{msg['role']}' in message. Only 'user' and 'assistant' roles are accepted."
-                )
-
-        # Store in MongoDB
-        if self.mongo and len(messages) >= 2:
-            try:
-                # Get last user and assistant messages
-                user_msg = None
-                assistant_msg = None
-                for msg in reversed(messages):
-                    if msg.get("role") == "user" and not user_msg:
-                        user_msg = msg.get("content")
-                    elif msg.get("role") == "assistant" and not assistant_msg:
-                        assistant_msg = msg.get("content")
-                    if user_msg and assistant_msg:
-                        break
-
-                if user_msg and assistant_msg:
-                    # Store truncated messages
-                    doc = {
-                        "user_id": user_id,
-                        "user_message": user_msg,
-                        "assistant_message": assistant_msg,
-                        "timestamp": datetime.now(timezone.utc),
-                    }
-                    self.mongo.insert_one(self.collection, doc)
-            except Exception as e:
-                logger.error(f"MongoDB storage error: {e}")  # Use logger.error
-
-        # Store in Zep
-        if not self.zep:
-            return
-
-        # Convert messages to Zep format
-        zep_messages = []
-        for msg in messages:
-            if "role" in msg and "content" in msg:
-                content = self._truncate(deepcopy(msg["content"]))
-                zep_msg = Message(
-                    role=msg["role"],
-                    content=content,
-                    role_type=msg["role"],
-                )
-                zep_messages.append(zep_msg)
-
-        # Add messages to Zep memory
-        if zep_messages:
-            try:
-                await self.zep.memory.add(session_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}"
-                        )  # Use logger.error
-
-                    try:
-                        await self.zep.memory.add_session(
-                            session_id=user_id, user_id=user_id
-                        )
-                    except Exception as e:
-                        logger.error(
-                            f"Zep session creation error: {e}"
-                        )  # Use logger.error
-                    await self.zep.memory.add(session_id=user_id, messages=zep_messages)
-                except Exception as e:
-                    logger.error(f"Zep memory addition error: {e}")  # Use logger.error
-                    return
-
-    async def retrieve(self, user_id: str) -> str:
-        """Retrieve memory context from Zep."""
-        try:
-            memories = ""
-            if self.zep:
-                memory = await self.zep.memory.get(session_id=user_id)
-                if memory and memory.context:
-                    memories = memory.context
-
-            return memories
-
-        except Exception as e:
-            logger.error(f"Error retrieving memories: {e}")  # Use logger.error
-            return ""
-
-    async def delete(self, user_id: str) -> None:
-        """Delete memory from both systems."""
-        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}")  # Use logger.error
-
-        if not self.zep:
-            return
-
-        try:
-            await self.zep.memory.delete(session_id=user_id)
-        except Exception as e:
-            logger.error(f"Zep memory deletion error: {e}")  # Use logger.error
-
-        try:
-            await self.zep.user.delete(user_id=user_id)
-        except Exception as e:
-            logger.error(f"Zep user deletion error: {e}")  # Use logger.error
-
-    def find(
-        self,
-        collection: str,
-        query: Dict,
-        sort: Optional[List[Tuple]] = None,
-        limit: int = 0,
-        skip: int = 0,
-    ) -> List[Dict]:  # pragma: no cover
-        """Find documents in MongoDB."""
-        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}")  # Use logger.error
-            return []
-
-    def count_documents(self, collection: str, query: Dict) -> int:
-        """Count documents in MongoDB."""
-        if not self.mongo:
-            return 0
-        return self.mongo.count_documents(collection, query)
-
-    def _truncate(self, text: str, limit: int = 2500) -> str:
-        """Truncate text to be within limits."""
-        if text is None:
-            raise AttributeError("Cannot truncate None text")
-
-        if not text:
-            return ""
-
-        if len(text) <= limit:
-            return text
-
-        # Try to truncate at last period before limit
-        last_period = text.rfind(".", 0, limit)
-        if last_period > 0:
-            return text[: last_period + 1]
-
-        # If no period found, truncate at limit and add ellipsis
-        return text[: limit - 3] + "..."