openai-moss-agents 0.1.0
make python module as code interpreter tool for OpenAI Agent by MOSS protocol
Requires Python: >=3.10

# Open-Moss-Agents

provide python module interface as tool for [OpenAI Agents](https://github.com/openai/openai-agents-python)

for example:

![math case](assets/math_case.jpg)

## Installation

from pip:

```bash
pip install openai-moss-agents
```

write agent with `MossProtocolTool`:

```python
from agents import Agent
from openai_moss_agents.moss_tool import MOSSProtocolTool

# tool without any python module, working as python interpreter
tool = MOSSProtocolTool(
    # provide python module as tool for the agent. 
    name="openai_moss_agents.example_moss_libs.terminal",
)

# generate instructions with `MOSS Protocol` information. 
instruction = tool.with_instruction("assistant for human")

# create an openai agent with `moss protocol tool` as agent tool. 
moss_agent = Agent(
    name="moss_agent",
    instructions=instruction,
    tools=[tool.as_agent_tool()]
)
```

You can create a lot of agents with different python modules.

If you want to see the instruction generate from any python module, run:

```bash
openai-moss-agents python_module_name

# example:
openai-moss-agents openai_moss_agents.example_moss_libs.math_lib
```

## Examples

use terminal by `Terminal` library.

![terminal case](assets/terminal_case.png)

run the examples by yourself:

```bash
git clone https://github.com/thirdgerb/openai-moss-agents  openai-moss-agents 

cd openai-moss-agents 
uv venv
uv sync --active --all-groups

# case 1, ask agent to use python interpreter
python examples/strawberry.py

# case 2, ask agent to use functions provided by `openai_moss_agents.example_moss_libs.math_lib`
python examples/openai_agent_baseline.py

# case 3, ask agent to use IoCContainer injections provided by `openai_moss_agents.example_moss_libs.terminal`
# !!!!!!!!! this case has risk, Agent will execute terminal command. don't ask agent to delete your root path.
python examples/moss_with_terminal.py
```

## Advanced Feature

If you want to provide `runtime injection` for the agent, you can create a library with `ghostos_moss.Moss`:

```python

# the imported abstract class and function are reflected into interface automatically
from ghostos_moss import Moss as Parent
from openai_moss_agents.example_moss_libs.terminal_lib.abcd import Terminal


# define a Moss Class in the module
# when LLM generate `run` function, the moss instance will pass to it 
# the typehint on Moss will be dynamic injected by IoC Container, see `openai_moss_agents.facade`
class Moss(Parent):
    # put the ModuleType or class values in the __watching__, will reflect their source code to LLM
    __watching__ = []

    # all the typehint classes will be reflected into interface for LLM
    # remember to provide the injections global IoCContainer before using, or give them to MossProtocolTool
    terminal: Terminal
    """your terminal """

# <moss-hide>

# the content between `# <moss-hide>` mark are not visible to LLM.
# you can do something here. 

# </moss-hide>
```

remember to register injection providers into IoCContainer by methods in `openai_moss_agents.facade`

## What Is MOSS Protocol ?

`MOSS` stands for `model-oriented operating system simulation`, which means:

1. reflect python module into model-oriented code interface.
2. with runtime-injections by ioc container, providing tools from the outer system (Agent Framework? OS? Embodied AI?).
3. let LLM understand the python context, use any library within it, execute the code generated by LLM in temporary
   module.
4. Save long-term variables in the `PyContext` object, for multi-turns conversation usage.

So MOSS is a protocol, provide Turing-complete programming interface
as the bridge for interaction between LLM and operating system.
This library is just an early experiment of the protocol
from [Project Ghostos](https://github.com/ghost-in-moss/GhostOS).

Full code-driven interaction represents the next-generation core paradigm for LLMAgent, following the era of
JSONSchemaTool.

The expected objects called through code
include `toolkit`, `libraries`, `terminal`, `agent`, `workflows`, `thinking`, `planning`, `knowledge`, `memory`...

Even allows a Meta-Agent to build its own agents swarm and toolkit through code, and call them immediately.
(Which is also dangerous), empowers the Agent to autonomously iterate and evolve.

We expect every programming language (like `TypedScript`) develop it own
popular model-oriented programming protocol,
or even `A universal model-oriented programming language`.

For more details:
[MOSS: Enabling Code-Driven Evolution and Context Management for AI Agents](https://arxiv.org/abs/2409.16120)