GhostOS

0.3.0 verified Sat May 09 auth: no python

GhostOS is a framework that simulates an operating system with a Python Code Interface for AI agents. It provides tools for agent reasoning, prompt management, and integration with various LLM services (OpenAI, DeepSeek, SiliconFlow, Aliyun). The current version is 0.3.0 (latest stable), with a development branch 0.4.0-dev1. Release cadence is irregular, with frequent minor patches.

pip install ghostos

Common errors

error AttributeError: module 'ghostos' has no attribute 'MossAgent' ↓

cause Importing directly from 'ghostos' instead of submodule 'ghostos.agents'.

fix

Use: from ghostos.agents import MossAgent

error openai.NotFoundError: Error code: 404 - {'error': {'message': 'The model `gpt-4` does not exist or you do not have access to it.'}} ↓

cause Model name is incorrect or API key lacks access.

fix

Check model name: use 'gpt-4' or 'gpt-3.5-turbo' that your API key has access to.

error ValueError: Cannot connect to realtime API: Missing OPENAI_PROXY environment variable ↓

cause Realtime feature requires OPENAI_PROXY even if empty.

fix

Set env var: export OPENAI_PROXY='' (empty string) or a valid proxy.

Warnings

breaking MossAgent is deprecated in v0.4.0-dev1; use MossGhost instead. ↓

fix Replace import: from ghostos.agents import MossGhost and use MossGhost class.

deprecated Importing from 'ghostos.prompter' module is being refactored; the PromptObjectModel API may change. ↓

fix Watch for changes in v0.4.0+ and migrate to the new prompt model.

gotcha OpenAI realtime feature requires both 'OPENAI_API_KEY' and 'OPENAI_PROXY' env vars; empty proxy may cause errors. ↓

fix Set OPENAI_PROXY to an empty string or a valid proxy URL.

bug Python 3.10 compatibility: some imports from 'typing' instead of 'typing_extensions' cause ImportError. ↓

fix Upgrade to 0.1.4+ or manually patch imports to use typing_extensions.

Install

pip install ghostos[realtime]

Imports

MossAgent
wrong
```
from ghostos import MossAgent
```
correct
```
from ghostos.agents import MossAgent
```
MossAgent was deprecated in v0.4.0-dev1 in favor of MossGhost; but in v0.3.0 it is still the correct import path.
MossGhost
wrong
```
from ghostos.moss import MossGhost
```
correct
```
from ghostos.agents import MossGhost
```
MossGhost is new in v0.4.0-dev1; in v0.3.0 it does not exist.

Quickstart

Minimal example: create a MossAgent and run a prompt.

import os
from ghostos.agents import MossAgent
from ghostos.core import AgentConfig

# Ensure API key is set
api_key = os.environ.get('OPENAI_API_KEY', '')
if not api_key:
    raise ValueError('OPENAI_API_KEY not set')

agent = MossAgent(
    config=AgentConfig(
        model='gpt-4',
        api_key=api_key
    )
)
response = agent.run('Hello, GhostOS!')
print(response)