Lexical scope-induced modularity should be documented

[eb8680]

The discussion and example snippets from #572 should probably be incorporated into the library documentation in some form given this behavior's practical importance in our programming model:

Agent already serves as a natural mechanism for encapsulating Templates and Tools into disjoint sets:

@Template.define
def write_poem(topic: str) -> str: ...

...

class Chatbot(Agent):
  @Template.define
  def respond(self, user_query: str) -> str: ...

  @Template.define
  def greet(self, user_name: str) -> str: ...

...

class TravelAdvisor(Agent):
  @Template.define
  def recommend_destination(self, user_query: str) -> str: ...

  @Tool.define
  def search_weather(self, city: str) -> str: ...

...

def main():
  chatbot = Chatbot()
  another_chatbot = Chatbot()
  travel_advisor = TravelAdvisor()

  @Template.define
  def simulate_user_interaction() -> str:
    """Use {another_chatbot} and {travel_advisor} to simulate an interaction between a user and assistant"""

  ...

main()

In this example, the lexical scope semantics of Template and Agent and the definitions of chatbot et al within the body of main naturally enforce that chatbot.respond has access to write_poem and chatbot.greet, but not to another_chatbot.respond or travel_advisor.recommend_destination. simulate_user_interaction has access to chatbot, another_chatbot, travel_advisor and write_poem, but none of these can see it.

This is exactly the behavior you'd expect for ordinary Python objects - for example, if Chatbot.respond was an ordinary instance method, it wouldn't have access to lexical variables in the body of main.

In contrast, if the body of main was inlined into the same lexical context (i.e. the top-level module scope where Chatbot and TravelAdvisor are defined), this encapsulation would be broken and all the Templates would see all of the others.

Originally posted by @eb8680 in #572

[datvo06]

One subtlety is that we can't inline either another_chatbot or travel_advisor in the prompt yet. But we should be able to mention their names.

[eb8680]

we can't inline either another_chatbot or travel_advisor in the prompt yet

Do you just mean we don't yet have an appropriate Encodable implementation for Agent, or do you think there's some other more fundamental limitation in play here?

[datvo06]

we can't inline either another_chatbot or travel_advisor in the prompt yet

Do you just mean we don't yet have an appropriate Encodable implementation for Agent, or do you think there's some other more fundamental limitation in play here?

I mean we dont have Encodable for Agent yet. I can try create one first