📝docs: refactor and update

docs/api/codebox.md

@@ -0,0 +1,35 @@
+# CodeBox Class API Reference
+
+## Constructor
+
+```python
+CodeBox(
+    session_id: str | None = None,
+    api_key: str | Literal["local", "docker"] | None = None,
+    factory_id: str | Literal["default"] | None = None,
+)
+```
+
+## Core Methods
+
+*Note*: Async methods are available when appened with `a` (e.g. `aexec()`).
+
+### Code Execution
+
+- `exec(code: str, kernel: Literal["ipython", "bash"] = "ipython") -> ExecResult`
+- `stream_exec(code: str, kernel: Literal["ipython", "bash"] = "ipython") -> AsyncGenerator[str, None]`
+
+### File Operations
+
+- `upload(remote_file_path: str, content: Union[BinaryIO, bytes, str]) -> RemoteFile`
+- `download(remote_file_path: str) -> RemoteFile`
+- `stream_download(remote_file_path: str) -> AsyncGenerator[bytes, None]`
+- `list_files() -> list[RemoteFile]`
+
+### Utility Methods
+
+- `healthcheck() -> Literal["healthy", "error"]`
+- `show_variables() -> dict[str, str]`
+- `restart() -> None`
+- `keep_alive(minutes: int = 15) -> None`
+- `install(*packages: str) -> str`

docs/api/types.md

@@ -0,0 +1,59 @@
+# Types API Reference
+
+## RemoteFile Class
+
+Represents a file stored in the remote CodeBox environment.
+
+```python
+RemoteFile(
+    path: str,
+    remote: CodeBox,
+    _size: int | None = None,
+    _content: bytes | None = None,
+)
+```
+
+### Properties
+
+- `name: str` - Returns the filename from the path
+- `_size: int | None` - Cached file size
+- `_content: bytes | None` - Cached file content
+
+### Methods
+
+*Note*: Async methods are available when appended with `a` (e.g. `aget_content()`).
+
+- `get_size() -> int` - Gets file size
+- `get_content() -> bytes` - Retrieves and caches file content
+- `save(local_path: str) -> None` - Saves file to local path
+
+## ExecChunk Class
+
+Represents a single chunk of execution output.
+
+```python
+ExecChunk(
+    type: Literal["txt", "img", "err"],
+    content: str
+)
+```
+
+The `type` field can be one of:
+
+- `txt`: Text output
+- `img`: Image output (base64 encoded)
+- `err`: Error output
+
+## ExecResult Class
+
+Container for execution results composed of multiple chunks.
+
+```python
+ExecResult(
+    chunks: list[ExecChunk]
+)
+```
+
+- `text: str` - Concatenated text output
+- `images: list[str]` - List of base64 encoded images
+- `errors: list[str]` - List of error messages

docs/concepts/architecture.md

@@ -0,0 +1,52 @@
+# Architecture Overview
+
+- [REST API](https://codeboxapi.com/docs)
+
+## Core Components
+
+- [Github Repo](https://github.com/shroominic/codebox-api)
+
+1. **Base Layer**
+   - Core `CodeBox` class
+   - Code execution interface
+   - File management interface
+   - Helper methods
+
+2. **Implementation Layer**
+   - `LocalBox`: Local running sandbox
+   - `RemoteBox`: REST API adapter for remote execution
+   - `DockerBox`: Docker adapter for local parallel execution
+
+3. **CodeBox API Service**
+   - REST API interface
+   - Fully isolated and scalable
+   - File and session management
+   - Custom factory support
+
+## Why is Sandboxing Important?
+
+Security is critical when deploying LLM Agents in production:
+
+- 🛡️ **Malicious Code Protection**: Isolated and secure execution
+- 🔐 **Injection Prevention**: Mitigation of prompt injection attacks
+- 🏰 **System Isolation**: No host system access
+- 📊 **Resource Control**: Memory and CPU limits
+
+## How It Works
+
+CodeBox uses a three-tier architecture:
+
+1. **API Layer**
+   - REST API for service interaction
+   - API key authentication
+   - Sync/Async operation support
+
+2. **Container Layer**
+   - Hardened Docker containers
+   - Complete host system isolation
+   - Automatic resource management
+
+3. **Storage Layer**
+   - Persistent file system
+   - Dependency management
+   - Package caching

docs/concepts/data_structures.md

@@ -0,0 +1,66 @@
+# Data Structures
+
+## Core Types
+
+### RemoteFile
+
+Represents a file in the CodeBox environment:
+
+```python
+class RemoteFile:
+    path: str          # File path in CodeBox
+    remote: CodeBox    # Associated CodeBox instance
+```
+
+### Methods
+
+- `get_content():` Get file contents
+- `aget_content():` Async get contents
+- `save(path):` Save to local path
+- `asave(path):` Async save to local path
+
+### ExecChunk
+
+Represents an execution output chunk:
+
+```python
+class ExecChunk:
+    type: Literal["txt", "img", "err"]  # Output type
+    content: str                        # Chunk content
+```
+
+### Types
+
+- `txt:` Text output
+- `img:` Base64 encoded image
+- `err:` Error message
+
+### ExecResult
+
+Complete execution result:
+
+```python
+class ExecResult:
+    chunks: List[ExecChunk]  # List of output chunks
+```
+
+### Properties
+
+- `text:` Combined text output
+- `images:` List of image outputs
+- `errors:` List of error messages
+
+### Usage Examples
+
+```python
+# File handling
+codebox = CodeBox()
+    # Upload and get file
+    file = codebox.upload("test.txt", "content")
+    content = file.get_content()
+
+    # Execute code and handle result
+    result = codebox.exec("print('hello')")
+    print(result.text)  # Text output
+    print(result.errors)  # Any errors
+```

docs/concepts/implementations.md

@@ -0,0 +1,66 @@
+# CodeBox Implementations
+
+## Implementation Overview
+
+### LocalBox
+
+- **Usage**: Local development and testing
+- **Requirements**: jupyter-kernel-gateway, ipython
+- **Configuration**: `api_key="local"`
+- **Advantages**:
+  - Rapid development
+  - No external dependencies
+  - Direct local environment access
+  - Fast execution for development
+- **Limitations**:
+  - No isolation
+  - Development only
+  - Local system resources
+
+### DockerBox
+
+- **Usage**: Isolated testing
+- **Requirements**: Docker installation
+- **Configuration**: `api_key="docker"`
+- **Advantages**:
+  - Local isolation
+  - Consistent environment
+  - No API costs
+  - Custom image support
+- **Limitations**:
+  - Requires Docker
+  - Local resource constraints
+  - Additional setup needed
+
+### RemoteBox
+
+- **Usage**: Production, scaling and cloud deployment
+- **Requirements**:
+  - Valid API key
+  - Internet connection
+- **Configuration**:
+
+```python
+codebox = CodeBox(api_key="...")
+```
+
+- **Key Features**:
+  - REST API integration
+  - Automatic session management
+  - Cloud-based file storage
+  - Managed package installation
+  - Resource usage monitoring
+- **Best for**:
+  - Production deployments
+  - Scalable applications
+  - Team collaborations
+
+## Implementation Comparison
+
+| Feature | RemoteBox | LocalBox | DockerBox |
+|---------|-----------|----------|------------|
+| Isolation | Full | Minimal | Full |
+| Setup Complexity | Low | Medium | High |
+| Resource Scaling | Yes | No | Limited |
+| Internet Required | Yes | No | No |
+| Cost | API Usage | Free | Free |