janito 3.9.0__tar.gz → 3.10.0__tar.gz

{janito-3.9.0 → janito-3.10.0}/.gitignore

@@ -1,66 +1,71 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Wheel files
-*.whl
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-.hypothesis/
-.pytest_cache/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# mypy
-.mypy_cache/
-.dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# Backup files
-*.bak
-
-# Ruff cache
-.ruff_cache/
-
-# Janito logs/history (if not needed in VCS)
-.janito/
-
-# MkDocs build output
-site/
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Wheel files
+*.whl
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Backup files
+*.bak
+
+# Ruff cache
+.ruff_cache/
+
+# Janito logs/history (if not needed in VCS)
+.janito/
+
+# MkDocs build output
+site/
+
+# Virtual environments
+.venv/
+venv/
+env/

{janito-3.9.0/janito.egg-info → janito-3.10.0}/PKG-INFO

@@ -1,84 +1,84 @@
-Metadata-Version: 2.4
-Name: janito
-Version: 3.9.0
-Summary: A new Python package called janito.
-Author-email: João Pinto <janito@ikignosis.org>
-Project-URL: Homepage, https://github.com/ikignosis/janito
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: attrs==25.3.0
-Requires-Dist: rich==14.0.0
-Requires-Dist: pathspec==0.12.1
-Requires-Dist: setuptools>=61.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: jinja2>=3.0.0
-Requires-Dist: prompt_toolkit>=3.0.51
-Requires-Dist: lxml>=5.4.0
-Requires-Dist: requests>=2.32.4
-Requires-Dist: bs4>=0.0.2
-Requires-Dist: questionary>=2.0.1
-Requires-Dist: openai>=1.68.0
-Requires-Dist: Pillow>=10.0.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: ruff==0.11.9; extra == "dev"
-Requires-Dist: detect-secrets==1.4.0; extra == "dev"
-Requires-Dist: codespell==2.4.1; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: questionary>=2.0.1; extra == "dev"
-Requires-Dist: setuptools_scm>=8.0; extra == "dev"
-Provides-Extra: coder
-Requires-Dist: janito-coder; extra == "coder"
-Dynamic: license-file
-
-# Janito
-
-```bash
-$ janito --help
-Usage: janito <command>
-
-Interact with Nine API resources. See https://docs.nineapis.ch for the full API docs.
-
-Run "janito <command> --help" for more information on a command.
-```
-
-## Setup
-
-```bash
-# If you have go already installed
-go install github.com/ninech/janito@latest
-
-# Homebrew
-brew install ninech/taps/janito
-
-# Debian/Ubuntu
-echo "deb [trusted=yes] https://repo.nine.ch/deb/ /" | sudo tee /etc/apt/sources.list.d/repo.nine.ch.list
-sudo apt-get update
-sudo apt-get install janito
-
-# Fedora/RHEL
-cat <<EOF > /etc/yum.repos.d/repo.nine.ch.repo
-[repo.nine.ch]
-name=Nine Repo
-baseurl=https://repo.nine.ch/yum/
-enabled=1
-gpgcheck=0
-EOF
-dnf install janito
-
-# Arch
-# Install yay: https://github.com/Jguer/yay#binary
-yay --version
-yay -S janito-bin
-```
-
-For Windows users, janito is also built for arm64 and amd64. You can download the
-latest exe file from the [releases](https://github.com/ninech/janito/releases) and
-install it.
-
-## Getting started
-
-* login to the API using `janito auth login`
-* run `janito --help` to get a list of all available commands
+Metadata-Version: 2.4
+Name: janito
+Version: 3.10.0
+Summary: A new Python package called janito.
+Author-email: João Pinto <janito@ikignosis.org>
+Project-URL: Homepage, https://github.com/ikignosis/janito
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs==25.3.0
+Requires-Dist: rich==14.0.0
+Requires-Dist: pathspec==0.12.1
+Requires-Dist: setuptools>=61.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: prompt_toolkit>=3.0.51
+Requires-Dist: lxml>=5.4.0
+Requires-Dist: requests>=2.32.4
+Requires-Dist: bs4>=0.0.2
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: openai>=1.68.0
+Requires-Dist: Pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff==0.11.9; extra == "dev"
+Requires-Dist: detect-secrets==1.4.0; extra == "dev"
+Requires-Dist: codespell==2.4.1; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: questionary>=2.0.1; extra == "dev"
+Requires-Dist: setuptools_scm>=8.0; extra == "dev"
+Provides-Extra: coder
+Requires-Dist: janito-coder; extra == "coder"
+Dynamic: license-file
+
+# Janito
+
+```bash
+$ janito --help
+Usage: janito <command>
+
+Interact with Nine API resources. See https://docs.nineapis.ch for the full API docs.
+
+Run "janito <command> --help" for more information on a command.
+```
+
+## Setup
+
+```bash
+# If you have go already installed
+go install github.com/ninech/janito@latest
+
+# Homebrew
+brew install ninech/taps/janito
+
+# Debian/Ubuntu
+echo "deb [trusted=yes] https://repo.nine.ch/deb/ /" | sudo tee /etc/apt/sources.list.d/repo.nine.ch.list
+sudo apt-get update
+sudo apt-get install janito
+
+# Fedora/RHEL
+cat <<EOF > /etc/yum.repos.d/repo.nine.ch.repo
+[repo.nine.ch]
+name=Nine Repo
+baseurl=https://repo.nine.ch/yum/
+enabled=1
+gpgcheck=0
+EOF
+dnf install janito
+
+# Arch
+# Install yay: https://github.com/Jguer/yay#binary
+yay --version
+yay -S janito-bin
+```
+
+For Windows users, janito is also built for arm64 and amd64. You can download the
+latest exe file from the [releases](https://github.com/ninech/janito/releases) and
+install it.
+
+## Getting started
+
+* login to the API using `janito auth login`
+* run `janito --help` to get a list of all available commands

janito-3.10.0/docs/agent/agent-lifecycle.md

@@ -0,0 +1,75 @@
+# Agent Lifecycle and Tool Execution Synchronization
+
+This document details the lifecycle of an agent in Janito, focusing on how state and events are synchronized with tool execution.
+
+## Overview
+
+The agent lifecycle in Janito involves several key phases, from initialization to tool execution and event handling. Understanding this lifecycle is crucial for developers working with or extending the agent system.
+
+## Agent Initialization
+
+1. **Configuration Loading**: The agent loads its configuration, including enabled tools, permissions, and other settings.
+2. **Event Bus Setup**: An event bus is initialized for internal communication between components.
+3. **Tool Registration**: Tools are registered with the appropriate adapters, making them available for execution.
+4. **Permission Initialization**: Global permission settings are established, determining which tools can be used.
+
+## Main Execution Loop
+
+The agent operates in a continuous loop that processes user input, executes tools, and responds with results:
+
+1. **Input Processing**: The agent receives input from the user or other sources.
+2. **Planning**: Based on the input, the agent determines which tools to use and in what order.
+3. **Tool Execution**: Tools are executed with the necessary parameters.
+4. **Result Processing**: The agent processes the results from tool executions.
+5. **Response Generation**: A response is generated and sent back to the user.
+
+## Tool Execution Lifecycle
+
+When a tool is executed, it goes through a specific lifecycle:
+
+1. **Discovery**: The agent looks up the tool by name in the tools registry.
+2. **Permission Validation**: The tool's required permissions are checked against the global allowed permissions.
+3. **Argument Validation**: The provided arguments are validated against the tool's signature and schema.
+4. **Path Security Check**: For tools that work with file paths, path security validation ensures that only allowed paths are accessed.
+5. **Execution**: The tool is executed with the provided arguments.
+6. **Event Publishing**: Throughout the execution process, various events are published to the event bus:
+
+   - `ToolCallStarted`: When a tool execution begins
+   - `ToolCallFinished`: When a tool execution completes successfully
+   - `ToolCallError`: When a tool execution encounters an error
+
+## Event Synchronization
+
+Events play a crucial role in synchronizing state throughout the agent lifecycle:
+
+1. **Tool Events**: Published during tool execution to track progress and handle errors.
+2. **Report Events**: Used for user-facing messages, including actions, errors, warnings, and success messages.
+3. **System Events**: Handle internal state changes and system-level notifications.
+
+The event bus ensures that all components can react to important events in real-time, maintaining consistency across the system.
+
+## State Management
+
+The agent maintains several types of state:
+
+1. **Configuration State**: Settings that control agent behavior.
+2. **Permission State**: Current allowed permissions for tool execution.
+3. **Execution State**: Information about currently running tools and their progress.
+4. **Conversation State**: History of interactions with the user.
+
+State changes are synchronized through the event bus, ensuring all components have access to the most current information.
+
+## Error Handling and Recovery
+
+The agent includes comprehensive error handling:
+
+1. **Tool Errors**: Caught and converted to `ToolCallException` with detailed error messages.
+2. **Permission Violations**: Detected and prevented before tool execution.
+3. **Path Security Violations**: Prevented through path validation.
+4. **Loop Protection**: Prevents infinite execution loops through decorator-based protection.
+
+When errors occur, they are published to the event bus and handled appropriately by the agent's error recovery mechanisms.
+
+## Conclusion
+
+The agent lifecycle in Janito is designed to be robust, secure, and extensible. By understanding how state and events are synchronized with tool execution, developers can effectively work with and extend the agent system.

janito-3.10.0/docs/agent/tools-workflow-lifecycle.md

@@ -0,0 +1,116 @@
+# Agent and Tools Workflow and Lifecycle
+
+This document explains how tools are integrated into Janito's agent system, covering their workflow from registration to execution and the overall lifecycle.
+
+## Overview
+
+Janito's agent system uses a modular approach to tool management, allowing for flexible registration, permission control, and execution of various tools. Tools are implemented as classes that inherit from `ToolBase` and are registered with a tools adapter.
+
+## Tool Registration
+
+### 1. Tool Implementation
+
+Tools are implemented as classes that inherit from `ToolBase`:
+
+- Must define a `permissions` attribute of type `ToolPermissions`
+- Must implement a `run` method with proper type hints and docstrings
+- Should have a unique `tool_name` class attribute
+
+Example:
+```python
+from janito.tools.tool_base import ToolBase, ToolPermissions
+from janito.plugins.adapters.local.adapter import register_local_tool
+
+@register_local_tool
+class MyTool(ToolBase):
+    """
+    Processes a file a given number of times.
+    """
+    permissions = ToolPermissions(read=True, write=True)
+    tool_name = "my_tool"
+
+    def run(self, filename: str, count: int) -> str:
+        """
+        Processes the specified file repeatedly.
+
+        Args:
+            filename (str): The path to the file to process.
+            count (int): How many times to process the file.
+
+        Returns:
+            str: Status message after processing.
+        """
+        # Implementation here
+        return f"Processed {filename} {count} times"
+```
+
+### 2. Tool Registration
+
+Tools can be registered in two ways:
+
+1. Using the `@register_local_tool` decorator
+2. Manually registering with a `LocalToolsAdapter` instance
+
+The decorator approach automatically registers the tool with the singleton adapter.
+
+## Tool Permissions
+
+Each tool defines its required permissions using the `ToolPermissions` named tuple:
+
+- `read`: Permission to read files
+- `write`: Permission to write/modify files
+- `execute`: Permission to execute commands
+
+These permissions are checked against the global allowed permissions at runtime.
+
+## Tool Execution Lifecycle
+
+### 1. Tool Discovery
+
+When the agent needs to execute a tool, it first looks up the tool by name using the tools adapter.
+
+### 2. Permission Validation
+
+The adapter checks if the tool's required permissions are allowed by the current permission settings.
+
+### 3. Argument Validation
+
+Before execution, the tool's arguments are validated against both the function signature and any defined schema.
+
+### 4. Path Security Check
+
+For tools that work with file paths, path security validation ensures that only allowed paths are accessed.
+
+### 5. Execution
+
+The tool is executed with the provided arguments, and the result is returned.
+
+### 6. Event Publishing
+
+Throughout the execution process, various events are published to the event bus:
+
+- `ToolCallStarted`: When a tool execution begins
+- `ToolCallFinished`: When a tool execution completes successfully
+- `ToolCallError`: When a tool execution encounters an error
+
+## Error Handling
+
+The tools adapter includes comprehensive error handling:
+
+- Missing or invalid arguments are caught and reported
+- Path security violations are detected and prevented
+- Loop protection prevents infinite execution loops
+- Runtime errors in tools are caught and converted to `ToolCallException`
+
+## Customization
+
+The tools system can be customized by:
+
+1. Implementing custom tools adapters for different execution environments
+2. Modifying permission settings at runtime
+3. Disabling specific tools through configuration
+4. Extending the base `ToolBase` class for specialized functionality
+
+## Conclusion
+
+Janito's agent and tools system provides a robust, secure, and extensible framework for integrating various functionalities. By following the established patterns for tool implementation and registration, developers can easily add new capabilities while maintaining security and consistency.

{janito-3.9.0 → janito-3.10.0}/docs/cerebras-setup.md

@@ -1,73 +1,73 @@
-# Cerebras Setup Guide
-
-This guide will help you set up Janito to use Cerebras as an LLM provider.
-
-## Prerequisites
-
-1. A Cerebras account
-2. An API key from Cerebras
-
-## Getting an API Key
-
-1. Visit the [Cerebras API Keys page](https://api.cerebras.ai/)
-2. Log in to your account
-3. Generate a new API key
-4. Copy the API key for use in Janito
-
-## Configuration
-
-To configure Janito to use Cerebras, you need to set your API key:
-
-```bash
-janito --set-api-key YOUR_CEREBRAS_API_KEY -p cerebras
-```
-
-Replace `YOUR_CEREBRAS_API_KEY` with the API key you obtained from Cerebras.
-
-## Usage
-
-After setting up your API key, you can use Cerebras models with Janito:
-
-```bash
-janito -p cerebras "Hello, how are you?"
-```
-
-By default, Janito will use the `qwen-3-coder-480b` model. You can specify a different model if needed:
-
-```bash
-janito -p cerebras -m qwen-3-coder-480b "Explain quantum computing"
-```
-
-## Available Models
-
-Cerebras offers several models through their API:
-
-**Production Models:**
-
-- `llama-4-scout-17b-16e-instruct`
-- `llama-3.3-70b`
-- `llama3.1-8b`
-- `qwen-3-32b`
-
-**Preview Models:**
-
-- `llama-4-maverick-17b-128e-instruct`
-- `qwen-3-235b-a22b-instruct-2507`
-- `qwen-3-235b-a22b-thinking-2507`
-- `qwen-3-coder-480b`
-- `gpt-oss-120b`
-
-**Notes:**
-
-- `qwen-3-coder-480b`: 32k context, reasoning-focused model with function calling support
-
-## Troubleshooting
-
-If you encounter issues:
-
-1. Verify your API key is correct and active
-2. Check that you have internet connectivity
-3. Ensure you're using a supported model name
-4. Check the Cerebras status page for any service outages
-
-For further assistance, consult the [Cerebras documentation](https://api.cerebras.ai/docs) or [Janito documentation](https://docs.janito.dev).
+# Cerebras Setup Guide
+
+This guide will help you set up Janito to use Cerebras as an LLM provider.
+
+## Prerequisites
+
+1. A Cerebras account
+2. An API key from Cerebras
+
+## Getting an API Key
+
+1. Visit the [Cerebras API Keys page](https://api.cerebras.ai/)
+2. Log in to your account
+3. Generate a new API key
+4. Copy the API key for use in Janito
+
+## Configuration
+
+To configure Janito to use Cerebras, you need to set your API key:
+
+```bash
+janito --set-api-key YOUR_CEREBRAS_API_KEY -p cerebras
+```
+
+Replace `YOUR_CEREBRAS_API_KEY` with the API key you obtained from Cerebras.
+
+## Usage
+
+After setting up your API key, you can use Cerebras models with Janito:
+
+```bash
+janito -p cerebras "Hello, how are you?"
+```
+
+By default, Janito will use the `qwen-3-coder-480b` model. You can specify a different model if needed:
+
+```bash
+janito -p cerebras -m qwen-3-coder-480b "Explain quantum computing"
+```
+
+## Available Models
+
+Cerebras offers several models through their API:
+
+**Production Models:**
+
+- `llama-4-scout-17b-16e-instruct`
+- `llama-3.3-70b`
+- `llama3.1-8b`
+- `qwen-3-32b`
+
+**Preview Models:**
+
+- `llama-4-maverick-17b-128e-instruct`
+- `qwen-3-235b-a22b-instruct-2507`
+- `qwen-3-235b-a22b-thinking-2507`
+- `qwen-3-coder-480b`
+- `gpt-oss-120b`
+
+**Notes:**
+
+- `qwen-3-coder-480b`: 32k context, reasoning-focused model with function calling support
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. Verify your API key is correct and active
+2. Check that you have internet connectivity
+3. Ensure you're using a supported model name
+4. Check the Cerebras status page for any service outages
+
+For further assistance, consult the [Cerebras documentation](https://api.cerebras.ai/docs).