Metadata-Version: 2.4
Name: skeptofox
Version: 0.1.0
Summary: A machine-human intelligence framework for declarative programming, Agentic AI and automation workflows
Project-URL: Homepage, https://github.com/skeptofox/skeptofox
Project-URL: Repository, https://github.com/skeptofox/skeptofox
Project-URL: Bug Tracker, https://github.com/skeptofox/skeptofox/issues
Author-email: skeptofox <skeptofox@gmail.com>
License: MIT License
        
        Copyright (c) 2025 skeptofox
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agentic ai,automation,declarative programming,human-in-the-loop,llm,machine intelligence,sandbox,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: packaging
Description-Content-Type: text/markdown

# skeptofox

skeptofox provides a powerful, declarative paradigm for designing, building, and analyzing complex systems where human insight and machine intelligence collaborate. Define your *what*, and Skeptofox orchestrates the *how*.

This version introduces the **Skeptofox Agent**: a fail-fast agent for secure, transparent, and deterministic execution of LLM-generated commands in a sandboxed environment.

-----

## Installation

```bash
pip install skeptofox
```

-----

## Quick Start

1.  **Create an instruction file** named `AGENT_FEED.txt` in your project directory.

    **File: `AGENT_FEED.txt`**

    ```
    AGENT_CREATE_AND_WRITE_FILE_START src/main.py
    AGENT_CREATE_AND_WRITE_FILE_CONTENT
    # My first Python script
    print("Hello, Skeptofox!")
    AGENT_CREATE_AND_WRITE_FILE_FINISH

    AGENT_LIST_FILES src
    ```

2.  **Create a runner script** to import and run the agent.

    **File: `run_agent.py`**

    ```python
    from skeptofox import agent

    # This will read AGENT_FEED.txt and execute the commands.
    agent.run()
    ```

3.  **Run the agent** from your terminal.

    ```bash
    python run_agent.py
    ```

-----

## Agent Architecture & Features

The agent's internal architecture is designed for maintainability, scalability, and clarity, adhering to the **Don't Repeat Yourself (DRY)** principle.

### Core Design & Architecture

  * **Centralized Command Parser**: The agent uses a single function, `parse_commands_from_content`, to read the `AGENT_FEED.txt` file once. It extracts all commands into a structured list, creating a single source of truth for the execution plan.
  * **Dynamic Command Dispatcher**: A `COMMAND_DISPATCHER` dictionary maps command types (e.g., `'CREATE_AND_WRITE_FILE'`) directly to their corresponding handler functions. This makes the system highly extensible.
  * **Modular, Single-Responsibility Handlers**: Each `handle_...` function performs only its core task, receiving its arguments directly. This improves code readability and testability.
  * **Consolidated Logging**: A single utility, `add_to_log`, handles both writing detailed, timestamped messages to `AGENT_LOG.txt` and printing user-friendly summaries to the console, streamlining all feedback.

### Security & Fail-Fast Workflow

The agent prioritizes a "no-compromise" approach to security and workflow integrity. It is designed to halt completely at the first sign of an error rather than continue in an uncertain state.

  * **Strict Sandboxing**: All file system operations are constrained to the agent's working directory. The `force_safepath` utility acts as a security gate for every file operation, raising a script-terminating exception if any path attempts to escape the sandbox.
  * **Fail-Fast Error Handling**: The agent operates on a strict fail-fast basis. The failure of **any** single command will immediately trigger an exception via the `invoke_exception` utility. **This halts the entire script**, preventing any subsequent commands from running and ensuring the system never proceeds in a partially failed or unpredictable state.
  * **Synchronous Human Approval Gate**: For critical operations like updating a file, the `request_human_approval` function halts execution and requires an explicit `'YES'` from the user. A rejection terminates the entire script via `sys.exit(1)`, fitting perfectly with the fail-fast philosophy.

### Implemented Commands & Capabilities

The agent has a comprehensive set of commands for file system management, documentation, and web interaction.

  * **Create & Write File**: Safely creates a new file and writes content to it.
  * **Update File (with Approval)**: Initiates the human-in-the-loop workflow to modify an existing file, staging versions in the `REFINERY` folder.
  * **Read File**: Reads the content of a file and displays it directly in the console.
  * **List Files**: Saves a formatted list of a directory's contents to a timestamped file in the `REFINERY` folder.
  * **Generate Docs**: Parses a Python file to extract class and function docstrings, generating a clean markdown documentation file.
  * **Generate Structured State Snapshot**: Scans a directory to produce a structured (text-analyzable) and reproducible snapshot as a series of `CREATE_AND_WRITE_FILE` commands.

### Internal Tooling & Utilities

  * **Diagnostic Logging**: All operations, status updates, and critical errors are logged with timestamps to `AGENT_LOG.txt`. This file serves as the definitive trace for diagnosing the agent's execution flow and pinpointing the exact cause of any failure.
  * **Refinery Folder**: A dedicated `REFINERY` directory is used as a staging and output area for generated artifacts like directory listings and file update comparisons.
  * **Fail-Fast Utilities**: The core workflow is enforced by specialized functions like `invoke_exception` (which centralizes the "log and crash" behavior) and `force_safepath`, ensuring consistent application of the agent's security principles.

-----

## Agent Command Reference

This provides a complete list of all commands available for the agent. These commands are designed to be placed in the `AGENT_FEED.txt` file for execution.

### File Management Commands

These commands are for interacting with files and directories within the agent's secure sandbox.

  * **Create & Write File**

      * **Syntax:**
        ```
        AGENT_CREATE_AND_WRITE_FILE_START <filepath>
        AGENT_CREATE_AND_WRITE_FILE_CONTENT
        <content>
        AGENT_CREATE_AND_WRITE_FILE_FINISH
        ```
      * **Description:** Creates a new file at the specified `<filepath>`. If the parent directories do not exist, it will create them. The multi-line `<content>` is then written to this new file.

  * **Update File (Requires Human Approval)**

      * **Syntax:**
        ```
        AGENT_UPDATE_FILE_START <filepath>
        AGENT_UPDATE_FILE_NEW_CONTENT
        <new_content>
        AGENT_UPDATE_FILE_FINISH
        ```
      * **Description:** Initiates a secure, human-in-the-loop process to update an existing file. It stages the original and updated versions in the `REFINERY` folder and prompts for explicit user approval before overwriting the original file. The script will terminate if approval is not granted.

  * **List Files**

      * **Syntax:** `AGENT_LIST_FILES <directory>`
      * **Description:** Lists all files and subdirectories within the specified `<directory>`. The output, tagged with `[DIR]` or `[FILE]`, is saved to a new, timestamped `.txt` file inside the `REFINERY` folder.

  * **Read File**

      * **Syntax:** `AGENT_READ_FILE <filepath>`
      * **Description:** Reads the full content of the file at `<filepath>` and prints it directly to the console for immediate review.

### Project & Documentation Commands

These commands are for higher-level project management and introspection.

  * **Generate Docs**

      * **Syntax:** `AGENT_GENERATE_DOCS <filepath>`
      * **Description:** Reads a Python file at `<filepath>` and generates a clean Markdown documentation file based on its class and function docstrings. The output is saved in the `docs` folder.


* **Generate Structured State Snapshot (Signature Ability)**
    * **Syntax:** `AGENT_GENERATE_STRUCTURED_STATE_SNAPSHOT <folderpath>`
    * **Description:** Captures a complete, structured snapshot of a directory's state. It generates a single text file that embeds the full contents of every file within a series of `AGENT_CREATE_AND_WRITE_FILE` commands. This output serves a dual purpose: it allows an LLM to perform complete project analysis in additon to being usable by the agent as feed to perfectly replicate the project's state.

-----

## License

This project is licensed under the MIT License.