UserSyncUI

Paused

File size: 17,849 Bytes

f6686e1

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
<meta name="generator" content="pdoc 0.10.0" />
<title>tinytroupe.tools.tiny_tool API documentation</title>
<meta name="description" content="" />
<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/sanitize.min.css" integrity="sha256-PK9q560IAAa6WVRRh76LtCaI8pjTJ2z11v0miyNNjrs=" crossorigin>
<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/typography.min.css" integrity="sha256-7l/o7C8jubJiy74VsKTidCy1yBkRtiUGbVkYBylBqUg=" crossorigin>
<link rel="stylesheet preload" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/github.min.css" crossorigin>
<style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}#sidebar > *:last-child{margin-bottom:2cm}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}h1:target,h2:target,h3:target,h4:target,h5:target,h6:target{background:var(--highlight-color);padding:.2em 0}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{margin-top:.6em;font-weight:bold}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}dt:target .name{background:var(--highlight-color)}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}td{padding:0 .5em}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%;height:100vh;overflow:auto;position:sticky;top:0}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js" integrity="sha256-Uv3H6lx7dJmRfRvH8TH6kJD1TSK1aFcwgx+mdg3epi8=" crossorigin></script>
<script>window.addEventListener('DOMContentLoaded', () => hljs.initHighlighting())</script>
</head>
<body>
<main>
<article id="content">
<header>
<h1 class="title">Module <code>tinytroupe.tools.tiny_tool</code></h1>
</header>
<section id="section-intro">
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">from tinytroupe.tools import logger
from tinytroupe.utils import JsonSerializableRegistry


class TinyTool(JsonSerializableRegistry):

    # Define what attributes should be serialized
    serializable_attributes = [&#34;name&#34;, &#34;description&#34;, &#34;real_world_side_effects&#34;]

    def __init__(self, name, description, owner=None, real_world_side_effects=False, exporter=None, enricher=None):
        &#34;&#34;&#34;
        Initialize a new tool.

        Args:
            name (str): The name of the tool.
            description (str): A brief description of the tool.
            owner (str): The agent that owns the tool. If None, the tool can be used by anyone.
            real_world_side_effects (bool): Whether the tool has real-world side effects. That is to say, if it has the potential to change the 
                state of the world outside of the simulation. If it does, it should be used with caution.
            exporter (ArtifactExporter): An exporter that can be used to export the results of the tool&#39;s actions. If None, the tool will not be able to export results.
            enricher (Enricher): An enricher that can be used to enrich the results of the tool&#39;s actions. If None, the tool will not be able to enrich results.
        
        &#34;&#34;&#34;
        self.name = name
        self.description = description
        self.owner = owner
        self.real_world_side_effects = real_world_side_effects
        self.exporter = exporter
        self.enricher = enricher

    def _process_action(self, agent, action: dict) -&gt; bool:
        raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)
    
    def _protect_real_world(self):
        if self.real_world_side_effects:
            logger.warning(f&#34; !!!!!!!!!! Tool {self.name} has REAL-WORLD SIDE EFFECTS. This is NOT just a simulation. Use with caution. !!!!!!!!!!&#34;)
        
    def _enforce_ownership(self, agent):
        if self.owner is not None and agent.name != self.owner.name:
            raise ValueError(f&#34;Agent {agent.name} does not own tool {self.name}, which is owned by {self.owner.name}.&#34;)
    
    def set_owner(self, owner):
        self.owner = owner

    def actions_definitions_prompt(self) -&gt; str:
        raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)
    
    def actions_constraints_prompt(self) -&gt; str:
        raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)

    def process_action(self, agent, action: dict) -&gt; bool:
        self._protect_real_world()
        self._enforce_ownership(agent)
        return self._process_action(agent, action)</code></pre>
</details>
</section>
<section>
</section>
<section>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-classes">Classes</h2>
<dl>
<dt id="tinytroupe.tools.tiny_tool.TinyTool"><code class="flex name class">
<span>class <span class="ident">TinyTool</span></span>
<span>(</span><span>name, description, owner=None, real_world_side_effects=False, exporter=None, enricher=None)</span>
</code></dt>
<dd>
<div class="desc"><p>A mixin class that provides JSON serialization, deserialization, and subclass registration.</p>
<p>Initialize a new tool.</p>
<h2 id="args">Args</h2>
<dl>
<dt><strong><code>name</code></strong> :&ensp;<code>str</code></dt>
<dd>The name of the tool.</dd>
<dt><strong><code>description</code></strong> :&ensp;<code>str</code></dt>
<dd>A brief description of the tool.</dd>
<dt><strong><code>owner</code></strong> :&ensp;<code>str</code></dt>
<dd>The agent that owns the tool. If None, the tool can be used by anyone.</dd>
<dt><strong><code>real_world_side_effects</code></strong> :&ensp;<code>bool</code></dt>
<dd>Whether the tool has real-world side effects. That is to say, if it has the potential to change the
state of the world outside of the simulation. If it does, it should be used with caution.</dd>
<dt><strong><code>exporter</code></strong> :&ensp;<code>ArtifactExporter</code></dt>
<dd>An exporter that can be used to export the results of the tool's actions. If None, the tool will not be able to export results.</dd>
<dt><strong><code>enricher</code></strong> :&ensp;<code>Enricher</code></dt>
<dd>An enricher that can be used to enrich the results of the tool's actions. If None, the tool will not be able to enrich results.</dd>
</dl></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">class TinyTool(JsonSerializableRegistry):

    # Define what attributes should be serialized
    serializable_attributes = [&#34;name&#34;, &#34;description&#34;, &#34;real_world_side_effects&#34;]

    def __init__(self, name, description, owner=None, real_world_side_effects=False, exporter=None, enricher=None):
        &#34;&#34;&#34;
        Initialize a new tool.

        Args:
            name (str): The name of the tool.
            description (str): A brief description of the tool.
            owner (str): The agent that owns the tool. If None, the tool can be used by anyone.
            real_world_side_effects (bool): Whether the tool has real-world side effects. That is to say, if it has the potential to change the 
                state of the world outside of the simulation. If it does, it should be used with caution.
            exporter (ArtifactExporter): An exporter that can be used to export the results of the tool&#39;s actions. If None, the tool will not be able to export results.
            enricher (Enricher): An enricher that can be used to enrich the results of the tool&#39;s actions. If None, the tool will not be able to enrich results.
        
        &#34;&#34;&#34;
        self.name = name
        self.description = description
        self.owner = owner
        self.real_world_side_effects = real_world_side_effects
        self.exporter = exporter
        self.enricher = enricher

    def _process_action(self, agent, action: dict) -&gt; bool:
        raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)
    
    def _protect_real_world(self):
        if self.real_world_side_effects:
            logger.warning(f&#34; !!!!!!!!!! Tool {self.name} has REAL-WORLD SIDE EFFECTS. This is NOT just a simulation. Use with caution. !!!!!!!!!!&#34;)
        
    def _enforce_ownership(self, agent):
        if self.owner is not None and agent.name != self.owner.name:
            raise ValueError(f&#34;Agent {agent.name} does not own tool {self.name}, which is owned by {self.owner.name}.&#34;)
    
    def set_owner(self, owner):
        self.owner = owner

    def actions_definitions_prompt(self) -&gt; str:
        raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)
    
    def actions_constraints_prompt(self) -&gt; str:
        raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)

    def process_action(self, agent, action: dict) -&gt; bool:
        self._protect_real_world()
        self._enforce_ownership(agent)
        return self._process_action(agent, action)</code></pre>
</details>
<h3>Ancestors</h3>
<ul class="hlist">
<li><a title="tinytroupe.utils.json.JsonSerializableRegistry" href="../utils/json.html#tinytroupe.utils.json.JsonSerializableRegistry">JsonSerializableRegistry</a></li>
</ul>
<h3>Subclasses</h3>
<ul class="hlist">
<li><a title="tinytroupe.tools.tiny_calendar.TinyCalendar" href="tiny_calendar.html#tinytroupe.tools.tiny_calendar.TinyCalendar">TinyCalendar</a></li>
<li><a title="tinytroupe.tools.tiny_word_processor.TinyWordProcessor" href="tiny_word_processor.html#tinytroupe.tools.tiny_word_processor.TinyWordProcessor">TinyWordProcessor</a></li>
</ul>
<h3>Class variables</h3>
<dl>
<dt id="tinytroupe.tools.tiny_tool.TinyTool.serializable_attributes"><code class="name">var <span class="ident">serializable_attributes</span></code></dt>
<dd>
<div class="desc"></div>
</dd>
</dl>
<h3>Methods</h3>
<dl>
<dt id="tinytroupe.tools.tiny_tool.TinyTool.actions_constraints_prompt"><code class="name flex">
<span>def <span class="ident">actions_constraints_prompt</span></span>(<span>self) ‑> str</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def actions_constraints_prompt(self) -&gt; str:
    raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)</code></pre>
</details>
</dd>
<dt id="tinytroupe.tools.tiny_tool.TinyTool.actions_definitions_prompt"><code class="name flex">
<span>def <span class="ident">actions_definitions_prompt</span></span>(<span>self) ‑> str</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def actions_definitions_prompt(self) -&gt; str:
    raise NotImplementedError(&#34;Subclasses must implement this method.&#34;)</code></pre>
</details>
</dd>
<dt id="tinytroupe.tools.tiny_tool.TinyTool.process_action"><code class="name flex">
<span>def <span class="ident">process_action</span></span>(<span>self, agent, action: dict) ‑> bool</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def process_action(self, agent, action: dict) -&gt; bool:
    self._protect_real_world()
    self._enforce_ownership(agent)
    return self._process_action(agent, action)</code></pre>
</details>
</dd>
<dt id="tinytroupe.tools.tiny_tool.TinyTool.set_owner"><code class="name flex">
<span>def <span class="ident">set_owner</span></span>(<span>self, owner)</span>
</code></dt>
<dd>
<div class="desc"></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def set_owner(self, owner):
    self.owner = owner</code></pre>
</details>
</dd>
</dl>
<h3>Inherited members</h3>
<ul class="hlist">
<li><code><b><a title="tinytroupe.utils.json.JsonSerializableRegistry" href="../utils/json.html#tinytroupe.utils.json.JsonSerializableRegistry">JsonSerializableRegistry</a></b></code>:
<ul class="hlist">
<li><code><a title="tinytroupe.utils.json.JsonSerializableRegistry.from_json" href="../utils/json.html#tinytroupe.utils.json.JsonSerializableRegistry.from_json">from_json</a></code></li>
<li><code><a title="tinytroupe.utils.json.JsonSerializableRegistry.to_json" href="../utils/json.html#tinytroupe.utils.json.JsonSerializableRegistry.to_json">to_json</a></code></li>
</ul>
</li>
</ul>
</dd>
</dl>
</section>
</article>
<nav id="sidebar">
<h1>Index</h1>
<div class="toc">
<ul></ul>
</div>
<ul id="index">
<li><h3>Super-module</h3>
<ul>
<li><code><a title="tinytroupe.tools" href="index.html">tinytroupe.tools</a></code></li>
</ul>
</li>
<li><h3><a href="#header-classes">Classes</a></h3>
<ul>
<li>
<h4><code><a title="tinytroupe.tools.tiny_tool.TinyTool" href="#tinytroupe.tools.tiny_tool.TinyTool">TinyTool</a></code></h4>
<ul class="">
<li><code><a title="tinytroupe.tools.tiny_tool.TinyTool.actions_constraints_prompt" href="#tinytroupe.tools.tiny_tool.TinyTool.actions_constraints_prompt">actions_constraints_prompt</a></code></li>
<li><code><a title="tinytroupe.tools.tiny_tool.TinyTool.actions_definitions_prompt" href="#tinytroupe.tools.tiny_tool.TinyTool.actions_definitions_prompt">actions_definitions_prompt</a></code></li>
<li><code><a title="tinytroupe.tools.tiny_tool.TinyTool.process_action" href="#tinytroupe.tools.tiny_tool.TinyTool.process_action">process_action</a></code></li>
<li><code><a title="tinytroupe.tools.tiny_tool.TinyTool.serializable_attributes" href="#tinytroupe.tools.tiny_tool.TinyTool.serializable_attributes">serializable_attributes</a></code></li>
<li><code><a title="tinytroupe.tools.tiny_tool.TinyTool.set_owner" href="#tinytroupe.tools.tiny_tool.TinyTool.set_owner">set_owner</a></code></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</main>
<footer id="footer">
<p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.10.0</a>.</p>
</footer>
</body>
</html>