GhostInShells · thirdgerb · Dec 22, 2024 · Oct 5, 2024 · Oct 5, 2024 · Oct 5, 2024
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,8 @@
 # ide
 .idea/
+dist
 debug.log
+.DS_Store
 *.thread.yml
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -103,7 +105,7 @@ ipython_config.py
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
+poetry.lock
 
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
@@ -163,4 +165,4 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-.vscode/
+.vscode/
diff --git a/README.md b/README.md
diff --git a/RELEASES.md b/RELEASES.md
@@ -0,0 +1,5 @@
+# Releases
+
+# v0.1.0-beta
+
+2024-12-22 beta version.
diff --git a/evaluation/__init__.py → docs/.nojekyll b/evaluation/__init__.py → docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/assets/architecture.png b/docs/assets/architecture.png
diff --git a/docs/assets/ask_sphero_spin_gif.gif b/docs/assets/ask_sphero_spin_gif.gif
diff --git a/docs/assets/ioc_container.png b/docs/assets/ioc_container.png
diff --git a/docs/assets/meta-agent-cycle.png b/docs/assets/meta-agent-cycle.png
diff --git a/docs/assets/moss_achitecture.png b/docs/assets/moss_achitecture.png
diff --git a/docs/assets/streamlit_chat.png b/docs/assets/streamlit_chat.png
diff --git a/docs/en/README.md b/docs/en/README.md
@@ -0,0 +1,206 @@
+# GhostOS
+
+> The AI `Ghosts` wonder in the `Shells`.
+
+* [中文文档](/en/README.md)
+* [Documents](/en/README.md)
+* [Discord Server](https://discord.gg/NG6VKwd5jV)
+
+(This document is translated from zh-cn to english by [Moonshot](https://moonshot.cn/))
+
+## Example
+
+Using Python code [SpheroBoltGPT](https://github.com/ghost-in-moss/GhostOS/tree/main/ghostos/demo/sphero/bolt_gpt.py),
+an intelligent robot with a [SpheroBolt](https://sphero.com/products/sphero-bolt) as its body is defined.
+If you have a SpheroBolt, running `ghostos web ghostos.demo.sphero.bolt_gpt` can start this robot.
+
+![SpheroBoltGPT](assets/ask_sphero_spin_gif.gif)
+
+The demo initially implements the following features:
+
+1. Real-time voice conversation.
+2. Control of body movements and drawing graphics on an 8x8 LED matrix.
+3. Learning skills that include actions and animations through natural language dialogue.
+4. Expressing emotions through movements during conversation.
+
+## Introduce
+
+`GhostOS` is an AI Agent framework designed to replace `JSON Schema `
+with a Turing-complete code interaction interface ([Moss Protocol](/en/concepts/moss_protocol.md)),
+becoming the core method for interaction between LLM and Agent system capabilities. For more details:
+[MOSS: Enabling Code-Driven Evolution and Context Management for AI Agents](https://arxiv.org/abs/2409.16120)
+
+The expected objects called through code
+include `tools`, `personality`, `agent swarm`, `workflows`, `thinking`, `planning`, `knowledge`, and `memory`.
+This allows a Meta-Agent to become an intelligent entity capable of continuous learning and growth through code
+generation and project management.
+
+And such an intelligent agent implemented with a code repository can also be shared and installed in the form of a
+repository.
+
+`GhostOS` Still in the early experimental developing, the current version mainly implements out-of-the-box capabilities,
+including:
+
+- [x] Turn a python file into an web agent
+- [x] Agent web UI built by [Streamlit Web](https://streamlit.io/)
+- [x] Support llms like `OpenAI`, `Moonshot`
+- [x] Support [OpenAI vision](https://platform.openai.com/docs/guides/vision)
+- [x] Support [OpenAI Realtime Beta](https://platform.openai.com/docs/guides/realtime)
+
+## Quick Start
+
+> `GhostOS` remains a beta AI project, strongly recommending installation in containers such as Docker rather than
+> running locally.
+
+Install `GhostOS` package:
+
+```bash
+pip install ghostos
+```
+
+Initialize `workspace` (directory `app` as default), The runtime files of the current version will be stored in the
+directory.
+
+```bash
+ghostos init
+```
+
+Configure the model. Default to use OpenAI `gpt-4o`, requiring the environment variable `OPENAI_API_KEY`.
+Or you can use configuration ui by streamlit:
+
+```bash
+ghostos config
+```
+
+Then test the default agent:
+
+```bash
+# run an agent with python filename or modulename
+ghostos web ghostos.demo.agents.jojo
+```
+
+Or turn a local Python file into an Agent,
+that can be instructed to call functions or methods within the file through natural language conversations.
+
+```bash
+ghostos web [my_path_file_path]
+```
+
+Install the extra dependencies for realtime:
+
+```bash
+# install realtime dependencies: pyaudio and websockets
+pip install ghostos[realtime] 
+
+# install spherov2 if you have sphero bolt
+pip install ghostos[sphero] 
+```
+
+ou can create a local Python file and define your own Agents. For more details
+
+* [Chatbot](/en/usages/chatbot.md): simplest chatbot
+* [MossAgent](/en/usages/moss_agent.md): an agent that can interact with the python module
+
+## Use In Python
+
+```python
+from ghostos.bootstrap import make_app_container, get_ghostos
+from ghostos.ghosts.chatbot import Chatbot
+
+# create your own root ioc container.
+# register or replace the dependencies by IoC service providers.
+container = make_app_container(...)
+
+# fetch the GhostOS instance.
+ghostos = get_ghostos(container)
+
+# Create a shell instance, which managing sessions that keep AI Ghost inside it.
+# and initialize the shell level dependency providers.
+shell = ghostos.create_shell("your robot shell")
+# Shell can handle parallel ghosts running, and communicate them through an EventBus.
+# So the Multi-Agent swarm in GhostOS is asynchronous.
+shell.background_run()  # Optional
+
+# need an instance implements `ghostos.abcd.Ghost` interface.
+my_chatbot: Chatbot = ...
+
+# use Shell to create a synchronous conversation channel with the Ghost.
+conversation = shell.sync(my_chatbot)
+
+# use the conversation channel to talk
+event, receiver = conversation.talk("hello?")
+with receiver:
+    for chunk in receiver.recv():
+        print(chunk.content)
+```
+
+## Developing Features
+
+* [ ] Out-of-the-box Agent capability libraries.
+* [ ] Variable type messaging and Streamlit rendering.
+* [ ] Asynchronous Multi-Agent.
+* [ ] Long-term task planning and execution.
+* [ ] Atomic thinking capabilities.
+* [ ] Automated execution and management of tree-based projects.
+* [ ] Configurable components of the framework.
+* [ ] Experiments with toy-level embodied intelligence.
+
+> GhostOS, as a personal project, currently lacks the energy to focus on improving documentation, storage modules,
+> stability, or security issues.
+>
+> The project's iteration will be centered on validating three directions for a long time:
+> code-driven embodied intelligence, code-based thinking capabilities, and code-based learning.
+> I will also aim to optimize out-of-the-box agent abilities.
+
+# So What is GhostOS?
+
+The GhostOS project is developed by the author for exploring AI applications. The basic idea is as follows:
+
+AI Agent technology has two parallel evolutionary paths:
+one is the perfection of the model's own capabilities, and the other is the evolution of the Agent engineering
+framework.
+The productivity level of the Agent framework determines the feasibility of AI models in practical application
+scenarios.
+
+GhostOS reflects the capabilities of an Agent from code into prompts, providing them to AI models,
+and the code generated by the models runs directly in the environment.
+Expecting the large language model do everything through a Turing-complete programming language interface,
+including computation, tool invocation, body control, personality switching, thinking paradigms, state scheduling,
+Multi-Agent, memory and recall, and other actions.
+
+This will have stronger interaction capabilities and lower overhead than methods based on JSON schema.
+The conversation data generated in this process can be used for post-training or reinforcement learning of the model,
+thereby continuously optimizing the code generation.
+
+The AI Agent itself is also defined by code.
+Therefore, a Meta-Agent can develop other Agents just like a normal programming task.
+
+Ideally, the Meta-Agent can write code, write its own tools, define memories and chain of thoughts with data structures,
+and develop other Agents for itself.
+
+![meta-agent-cycle](assets/meta-agent-cycle.png)
+
+Furthermore, most complex tasks with rigorous steps can be described using tree or graph data structures.
+Constructing a nested graph or tree using methods like JSON is very difficult,
+while using programming languages is the most efficient.
+
+models can consolidate the results learned from conversations into nodes in the code,
+and then plan them into trees or graphs, thereby executing sufficiently complex tasks.
+
+In this way, an AI Agent can store the knowledge and capabilities learned from natural language in the form of files and
+code,
+thereby evolving itself. This is a path of evolution beyond model iteration.
+
+Based on this idea,
+GhostOS aims to turn an Agent swarm into a project constructed through code.
+The Agents continuously precipitate new knowledge and capabilities in the form of code, enriching the project.
+The Agent project can be copied, shared, or deployed in the form of repositories,
+
+In this new form of productivity, interacting purely through code is the most critical step.
+
+The author's ultimate goal is not `GhostOS` itself,
+but to verify and promote the code interaction design and applications.
+The hope is that one day, agents, paradigms, bodies, and tools for AI Agents can all be designed based on the same
+programming language protocols,
+achieving cross-project universality.
+
diff --git a/docs/en/_navbar.md b/docs/en/_navbar.md
@@ -0,0 +1,2 @@
+* [Chinese](/zh-cn/)
+* [En](/en/)
diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md
@@ -0,0 +1,23 @@
+* [Home](/en/)
+* Getting Started
+    * [Installation](/en/getting_started/installation.md)
+    * [Configuration](/en/getting_started/configuration.md)
+    * [Chat](/en/getting_started/chat_with_ghost.md)
+    * [Scripts](/en/getting_started/scripts.md)
+* Concepts
+    * [Design](/en/concepts/abcd.md)
+    * [Moss Protocol](/en/concepts/moss_protocol.md)
+    * [IoC Container](/en/concepts/ioc_container.md)
+    * [EntityMeta](/en/concepts/entity_meta.md)
+    * [Prompter](/en/concepts/prompter.md)
+* Usages
+    * [Ghost](/en/usages/ghost.md)
+    * [Chatbot](/en/usages/chatbot.md)
+    * [MossAgent](/en/usages/moss_agent.md)
+* [Libraries](/en/libraries/libraries.md)
+* Frameworks
+    * [Messages](/en/frameworks/messages.md)
+    * [LLMs](/en/frameworks/llms.md)
+    * [EventBus](/en/frameworks/eventbus.md)
+    * [Tasks](/en/frameworks/tasks.md)
+    * [Threads](/en/frameworks/threads.md)
diff --git a/docs/en/concepts/abcd.md b/docs/en/concepts/abcd.md
@@ -0,0 +1,47 @@
+# Abstract Class Design
+
+The abstract design of GhostOS adheres to the principle of interface-oriented programming.
+All modules are designed using abstract classes, and implementations are assembled through
+the [IoC Container](/en/concepts/ioc_container.md)
+
+![architecture](../../assets/architecture.png)
+
+The basic interrelationships of these abstractions and their usage logic are as follows:
+
+```python
+from ghostos.abcd import GhostOS, Shell, Conversation, Ghost
+from ghostos.container import Container
+from ghostos.bootstrap import make_app_container, get_ghostos
+
+# create your own root ioc container.
+# register or replace the dependencies by IoC service providers.
+container: Container = make_app_container(...)
+
+# fetch the GhostOS instance.
+ghostos: GhostOS = get_ghostos(container)
+
+# Create a shell instance, which managing sessions that keep AI Ghost inside it.
+# and initialize the shell level dependency providers.
+shell: Shell = ghostos.create_shell("your robot shell")
+# Shell can handle parallel ghosts running, and communicate them through an EventBus.
+# So the Multi-Agent swarm in GhostOS is asynchronous.
+shell.background_run()  # Optional
+
+# need an instance implements `ghostos.abcd.Ghost` interface.
+my_chatbot: Ghost = ...
+
+# use Shell to create a synchronous conversation channel with the Ghost.
+conversation: Conversation = shell.sync(my_chatbot)
+
+# use the conversation channel to talk
+event, receiver = conversation.talk("hello?")
+with receiver:
+    for chunk in receiver.recv():
+        print(chunk.content)
+
+```
+
+For detailed content, please check the source code. [ghostos.abcd.concepts](https://github.com/ghost-in-moss/GhostOS/tree/main/ghostos/abcd/concepts.py)
+
+> Abstract design-related introductions can be quite complex; 
+> only complete the documentation when I have the energy (T_T).
diff --git a/docs/en/concepts/entity_meta.md b/docs/en/concepts/entity_meta.md
@@ -0,0 +1,16 @@
+# Entity Meta
+
+A code-driven AI Agent needs to store various data during its operation, a
+nd also be able to restore variables in subsequent operations.
+Considering a distributed system or an interruptible Agent, these data need a long-term storage solution.
+
+`GhostOS`, based on `pickle` and `pydantic`, has
+implemented [EntityMeta](https://github.com/ghost-in-moss/GhostOS/tree/main/ghostos/entity.py).
+
+It aims to:
+
+1. Serialize and deserialize the vast majority of accessible Python data structures
+2. Provide a universal container and API for data manipulation
+3. Ensure data readability as much as possible.
+
+More technical details can be seen in the code.