deploy: 67ac756

Author: truemagic-coder

.doctrees/api/index.doctree

@@ -78,7 +78,9 @@ <h1>Source code for solana_agent.client.solana_agent</h1><div class="highlight">
 
 <span class="kn">import</span><span class="w"> </span><span class="nn">json</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">importlib.util</span>
-<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncGenerator</span><span class="p">,</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">Any</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Literal</span><span class="p">,</span> <span class="n">Optional</span><span class="p">,</span> <span class="n">Union</span>
+<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncGenerator</span><span class="p">,</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">Any</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Literal</span><span class="p">,</span> <span class="n">Optional</span><span class="p">,</span> <span class="n">Type</span><span class="p">,</span> <span class="n">Union</span>
+
+<span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span>
 
 <span class="kn">from</span><span class="w"> </span><span class="nn">solana_agent.factories.agent_factory</span><span class="w"> </span><span class="kn">import</span> <span class="n">SolanaAgentFactory</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">solana_agent.interfaces.client.client</span><span class="w"> </span><span class="kn">import</span> <span class="n">SolanaAgent</span> <span class="k">as</span> <span class="n">SolanaAgentInterface</span>
@@ -144,7 +146,8 @@ <h1>Source code for solana_agent.client.solana_agent</h1><div class="highlight">
         <span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;mp4&quot;</span><span class="p">,</span>
         <span class="n">router</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">RoutingInterface</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
         <span class="n">images</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">]]]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">AsyncGenerator</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">],</span> <span class="kc">None</span><span class="p">]:</span>  <span class="c1"># pragma: no cover</span>
+        <span class="n">output_model</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Type</span><span class="p">[</span><span class="n">BaseModel</span><span class="p">]]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">AsyncGenerator</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">bytes</span><span class="p">,</span> <span class="n">BaseModel</span><span class="p">],</span> <span class="kc">None</span><span class="p">]:</span>  <span class="c1"># pragma: no cover</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;Process a user message (text or audio) and optional images, returning the response stream.</span>
 
 <span class="sd">        Args:</span>
@@ -158,6 +161,7 @@ <h1>Source code for solana_agent.client.solana_agent</h1><div class="highlight">
 <span class="sd">            audio_input_format: Audio input format</span>
 <span class="sd">            router: Optional routing service for processing</span>
 <span class="sd">            images: Optional list of image URLs (str) or image bytes.</span>
+<span class="sd">            output_model: Optional Pydantic model for structured output</span>
 
 <span class="sd">        Returns:</span>
 <span class="sd">            Async generator yielding response chunks (text strings or audio bytes)</span>
@@ -173,6 +177,7 @@ <h1>Source code for solana_agent.client.solana_agent</h1><div class="highlight">
             <span class="n">audio_input_format</span><span class="o">=</span><span class="n">audio_input_format</span><span class="p">,</span>
             <span class="n">prompt</span><span class="o">=</span><span class="n">prompt</span><span class="p">,</span>
             <span class="n">router</span><span class="o">=</span><span class="n">router</span><span class="p">,</span>
+            <span class="n">output_model</span><span class="o">=</span><span class="n">output_model</span><span class="p">,</span>
         <span class="p">):</span>
             <span class="k">yield</span> <span class="n">chunk</span></div>
 

.doctrees/environment.pickle

@@ -234,6 +234,40 @@ Image/Text Streaming
       print(response, end="")
 
 
+Structured Outputs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from solana_agent import SolanaAgent
+
+   config = {
+      "openai": {
+         "api_key": "your-openai-api-key",
+      },
+      "agents": [
+         {
+               "name": "researcher",
+               "instructions": "You are a research expert.",
+               "specialization": "Researcher",
+         }
+      ],
+   }
+
+   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())
+
+
 Command Line Interface (CLI)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -474,6 +508,8 @@ Guardrails - Optional
 
 Guardrails allow you to process and potentially modify user input before it reaches the agent (Input Guardrails) and agent output before it's sent back to the user (Output Guardrails). This is useful for implementing safety checks, content moderation, data sanitization, or custom transformations.
 
+Guardrails don't apply to structured outputs.
+
 Solana Agent provides a built-in PII scrubber based on scrubadub.
 
 .. code-block:: python
@@ -515,6 +551,8 @@ Solana Agent provides a built-in PII scrubber based on scrubadub.
 Example Custom Guardrails - Optional
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Guardrails don't apply to structured outputs.
+
 .. code-block:: python
 
    from solana_agent import InputGuardrail, OutputGuardrail

.doctrees/index.doctree

@@ -169,7 +169,7 @@ <h1>API Reference<a class="headerlink" href="#api-reference" title="Link to this
 </dl>
 <dl class="py method">
 <dt class="sig sig-object py" id="solana_agent.client.solana_agent.SolanaAgent.process">
-<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">process</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">user_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">message</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prompt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'text'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_voice</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'nova'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_instructions</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'You</span> <span class="pre">speak</span> <span class="pre">in</span> <span class="pre">a</span> <span class="pre">friendly</span> <span class="pre">and</span> <span class="pre">helpful</span> <span class="pre">manner.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_output_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'aac'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_input_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'mp4'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">router</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">images</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/solana_agent/client/solana_agent.html#SolanaAgent.process"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#solana_agent.client.solana_agent.SolanaAgent.process" title="Link to this definition"></a></dt>
+<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">process</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">user_id</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">message</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">prompt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'text'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_voice</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'nova'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_instructions</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'You</span> <span class="pre">speak</span> <span class="pre">in</span> <span class="pre">a</span> <span class="pre">friendly</span> <span class="pre">and</span> <span class="pre">helpful</span> <span class="pre">manner.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_output_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'aac'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">audio_input_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'mp4'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">router</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">images</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">output_model</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/solana_agent/client/solana_agent.html#SolanaAgent.process"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#solana_agent.client.solana_agent.SolanaAgent.process" title="Link to this definition"></a></dt>
 <dd><p>Process a user message (text or audio) and optional images, returning the response stream.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
@@ -184,13 +184,14 @@ <h1>API Reference<a class="headerlink" href="#api-reference" title="Link to this
 <li><p><strong>audio_input_format</strong> (<em>Literal</em><em>[</em><em>'flac'</em><em>, </em><em>'mp3'</em><em>, </em><em>'mp4'</em><em>, </em><em>'mpeg'</em><em>, </em><em>'mpga'</em><em>, </em><em>'m4a'</em><em>, </em><em>'ogg'</em><em>, </em><em>'wav'</em><em>, </em><em>'webm'</em><em>]</em>) – Audio input format</p></li>
 <li><p><strong>router</strong> (<em>RoutingService</em><em> | </em><em>None</em>) – Optional routing service for processing</p></li>
 <li><p><strong>images</strong> (<em>List</em><em>[</em><em>str</em><em> | </em><em>bytes</em><em>] </em><em>| </em><em>None</em>) – Optional list of image URLs (str) or image bytes.</p></li>
+<li><p><strong>output_model</strong> (<em>Type</em><em>[</em><em>BaseModel</em><em>] </em><em>| </em><em>None</em>) – Optional Pydantic model for structured output</p></li>
 </ul>
 </dd>
 <dt class="field-even">Returns<span class="colon">:</span></dt>
 <dd class="field-even"><p>Async generator yielding response chunks (text strings or audio bytes)</p>
 </dd>
 <dt class="field-odd">Return type<span class="colon">:</span></dt>
-<dd class="field-odd"><p><em>AsyncGenerator</em>[str | bytes, None]</p>
+<dd class="field-odd"><p><em>AsyncGenerator</em>[str | bytes | <em>BaseModel</em>, None]</p>
 </dd>
 </dl>
 </dd></dl>

_modules/solana_agent/client/solana_agent.html

@@ -289,6 +289,38 @@ <h3>Image/Text Streaming<a class="headerlink" href="#image-text-streaming" title
 </pre></div>
 </div>
 </section>
+<section id="structured-outputs">
+<h3>Structured Outputs<a class="headerlink" href="#structured-outputs" title="Link to this heading"></a></h3>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">solana_agent</span><span class="w"> </span><span class="kn">import</span> <span class="n">SolanaAgent</span>
+
+<span class="n">config</span> <span class="o">=</span> <span class="p">{</span>
+   <span class="s2">&quot;openai&quot;</span><span class="p">:</span> <span class="p">{</span>
+      <span class="s2">&quot;api_key&quot;</span><span class="p">:</span> <span class="s2">&quot;your-openai-api-key&quot;</span><span class="p">,</span>
+   <span class="p">},</span>
+   <span class="s2">&quot;agents&quot;</span><span class="p">:</span> <span class="p">[</span>
+      <span class="p">{</span>
+            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;researcher&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;instructions&quot;</span><span class="p">:</span> <span class="s2">&quot;You are a research expert.&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;specialization&quot;</span><span class="p">:</span> <span class="s2">&quot;Researcher&quot;</span><span class="p">,</span>
+      <span class="p">}</span>
+   <span class="p">],</span>
+<span class="p">}</span>
+
+<span class="n">solana_agent</span> <span class="o">=</span> <span class="n">SolanaAgent</span><span class="p">(</span><span class="n">config</span><span class="o">=</span><span class="n">config</span><span class="p">)</span>
+
+<span class="k">class</span><span class="w"> </span><span class="nc">ResearchProposal</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span>
+   <span class="n">title</span><span class="p">:</span> <span class="nb">str</span>
+   <span class="n">abstract</span><span class="p">:</span> <span class="nb">str</span>
+   <span class="n">key_points</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span>
+
+<span class="n">full_response</span> <span class="o">=</span> <span class="kc">None</span>
+<span class="k">async</span> <span class="k">for</span> <span class="n">response</span> <span class="ow">in</span> <span class="n">solana_agent</span><span class="o">.</span><span class="n">process</span><span class="p">(</span><span class="s2">&quot;user123&quot;</span><span class="p">,</span> <span class="s2">&quot;Research the life of Ben Franklin - the founding Father.&quot;</span><span class="p">,</span> <span class="n">output_model</span><span class="o">=</span><span class="n">ResearchProposal</span><span class="p">):</span>
+   <span class="n">full_response</span> <span class="o">=</span> <span class="n">response</span>
+
+<span class="nb">print</span><span class="p">(</span><span class="n">full_response</span><span class="o">.</span><span class="n">model_dump</span><span class="p">())</span>
+</pre></div>
+</div>
+</section>
 <section id="command-line-interface-cli">
 <h3>Command Line Interface (CLI)<a class="headerlink" href="#command-line-interface-cli" title="Link to this heading"></a></h3>
 <p>Solana Agent includes a command-line interface (CLI) for text-based chat using a configuration file.</p>
@@ -508,6 +540,7 @@ <h3>Example for KB (pdf) - Optional<a class="headerlink" href="#example-for-kb-p
 <section id="guardrails-optional">
 <h3>Guardrails - Optional<a class="headerlink" href="#guardrails-optional" title="Link to this heading"></a></h3>
 <p>Guardrails allow you to process and potentially modify user input before it reaches the agent (Input Guardrails) and agent output before it’s sent back to the user (Output Guardrails). This is useful for implementing safety checks, content moderation, data sanitization, or custom transformations.</p>
+<p>Guardrails don’t apply to structured outputs.</p>
 <p>Solana Agent provides a built-in PII scrubber based on scrubadub.</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">solana_agent</span><span class="w"> </span><span class="kn">import</span> <span class="n">SolanaAgent</span>
 
@@ -547,6 +580,7 @@ <h3>Guardrails - Optional<a class="headerlink" href="#guardrails-optional" title
 </section>
 <section id="example-custom-guardrails-optional">
 <h3>Example Custom Guardrails - Optional<a class="headerlink" href="#example-custom-guardrails-optional" title="Link to this heading"></a></h3>
+<p>Guardrails don’t apply to structured outputs.</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">solana_agent</span><span class="w"> </span><span class="kn">import</span> <span class="n">InputGuardrail</span><span class="p">,</span> <span class="n">OutputGuardrail</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">logging</span>