📝docs: refactor and update

Author: TincoNomad

docs/api.md

@@ -0,0 +1,43 @@
+# 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
+
+### Code Execution
+
+- `exec(code: str, kernel: Literal["ipython", "bash"] = "ipython") -> ExecResult`
+- `aexec(code: str, kernel: Literal["ipython", "bash"] = "ipython") -> ExecResult`
+
+### File Operations
+
+- `upload(remote_file_path: str, content: Union[BinaryIO, bytes, str]) -> RemoteFile`
+- `download(remote_file_path: str) -> RemoteFile`
+- `list_files() -> List[RemoteFile]`
+
+### Package Management
+
+- `install(*packages: str) -> str`
+- `ainstall(*packages: str) -> str`
+
+### Health Checks
+
+- `healthcheck() -> Literal["healthy", "error"]`
+- `ahealthcheck() -> Literal["healthy", "error"]`
+
+## Deprecated Methods
+
+The following methods are deprecated and should be replaced with their newer alternatives:
+
+- `run()` → Use `exec()` instead
+- `arun()` → Use `aexec()` instead
+- `status()` → Use `healthcheck()` instead
+- `astatus()` → Use `ahealthcheck()` instead

docs/api/codebox.md

@@ -0,0 +1,29 @@
+# Exceptions API Reference
+
+## CodeBoxError
+
+The main exception class for CodeBox-related errors. Provides detailed context about API errors.
+
+### Attributes:
+
+- `status_code`: HTTP status code from the API response
+- `response_json`: Parsed JSON body from the response
+- `headers`: Response headers
+
+### Common Error Cases
+
+```python
+from codeboxapi import CodeBox, CodeBoxError
+
+try:
+    with CodeBox() as codebox:
+        codebox.exec("invalid python code")
+except CodeBoxError as e:
+    print(f"Error {e.status_code}: {e.response_json}")
+```
+
+### Error Types
+1. Authentication Errors (401)
+2. Rate Limit Errors (429)
+3. Execution Errors (400)
+4. Server Errors (500)

docs/api/exceptions.md

@@ -0,0 +1,41 @@
+# Settings API Reference
+
+## CodeBoxSettings
+
+The `CodeBoxSettings` class manages the configuration for the CodeBox client. It inherits from Pydantic's `BaseSettings` class and loads values from environment variables.
+
+### Environment Variables and Settings
+
+#### API Settings
+- `CODEBOX_API_KEY: str | None = None`
+  Your API key for authentication
+- `CODEBOX_BASE_URL: str = "https://codeboxapi.com/api/v2"`
+  Base URL for the API
+- `CODEBOX_TIMEOUT: int = 20`
+  Request timeout in seconds
+
+#### Additional Settings
+- `CODEBOX_FACTORY_ID: str = "default"`
+  Custom Docker image or environment
+- `CODEBOX_SESSION_ID: str | None = None`
+  Custom session identifier
+
+#### Logging Settings
+- `VERBOSE: bool = False`
+  Determines if verbose logging is enabled
+- `SHOW_INFO: bool = True`
+  Determines if information-level logging is enabled
+
+### Usage
+
+```python
+from codeboxapi import CodeBox
+# Using environment variables
+codebox = CodeBox()
+# Or explicitly in code
+codebox = CodeBox(
+    api_key="your-api-key",
+    base_url="https://custom-url.com/api/v1",
+    timeout=30
+)
+``` 

docs/api/settings.md

@@ -0,0 +1,38 @@
+## Architecture Overview
+- [REST API](https://codeboxapi.com/docs)
+### Core Components
+- [Github Repo](https://github.com/shroominic/codebox-api)
+1. **Base Layer**
+   - Abstract `BaseBox` class
+   - Core execution interface
+   - Session management
+   - Resource handling
+2. **Implementation Layer**
+   - `LocalBox`: Local development environment
+   - `DockerBox`: Containerized execution
+   - `RemoteBox`: Cloud execution service
+3. **API Layer**
+   - REST API interface
+   - Async/Sync operations
+   - File management
+   - Package handling
+## 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/architecture.md

@@ -72,4 +72,4 @@ Custom exception class raised when there is an error response from the API. It i
 - Response JSON body
 - Response headers
 
-This provides an easy way to handle errors with additional context.
+This provides an easy way to handle errors with additional context.

docs/concepts.md renamed to docs/concepts/components.md

@@ -0,0 +1,57 @@
+# 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
+    _size: int        # File size in bytes
+    _content: bytes   # File content
+```
+
+### 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
+with CodeBox() as 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/data_structures.md

@@ -0,0 +1,61 @@
+# 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="your-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 |