azathoth 0.0.1__tar.gz

azathoth-0.0.1/.gitignore

@@ -0,0 +1,20 @@
+# all that start with a dot except .gitignore
+.*
+!.gitignore
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Rust-generated files
+/target/
+temp/
+
+# lock files
+**/**.lock
+
+translations

azathoth-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fernando Bryan Reza Campos
+
+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.

azathoth-0.0.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: azathoth
+Version: 0.0.1
+Summary: Azathoth: Dual-Protocol AI Intelligence Layer (MCP + A2A)
+Author-email: Fernando Bryan Reza Campos <fer.rezac@outlook.com>
+License: MIT License
+        
+        Copyright (c) 2025 Fernando Bryan Reza Campos
+        
+        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: a2a,agent,ai,automation,mcp
+Requires-Python: >=3.14
+Requires-Dist: fastmcp>=3.2.4
+Requires-Dist: gitingest>=0.3.1
+Requires-Dist: google-genai>=1.73.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: pydantic>=2.13.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: typer>=0.24.1
+Provides-Extra: agent
+Requires-Dist: a2a-sdk[http-server]>=0.3.24; extra == 'agent'
+Provides-Extra: clipboard
+Requires-Dist: pyperclip>=1.11.0; extra == 'clipboard'
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.408; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.15.10; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/Yrrrrrf/azathoth/main/assets/img/abstract-shape.png" alt="Azathoth Icon" width="128" height="128">
+  <div align="center">Azathoth</div>
+</h1>
+
+<div align="center">
+
+<!-- CORE BADGES -->
+
+[![GitHub: Repo](https://img.shields.io/badge/Azathoth-58A6FF?&logo=github)](https://github.com/Yrrrrrf/Azathoth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+<!-- Rust based projects -->
+
+[![Crates.io](https://img.shields.io/crates/v/azathoth)](https://crates.io/crates/azathoth)
+[![Crates.io Downloads](https://img.shields.io/crates/d/azathoth)](https://crates.io/crates/azathoth)
+[![docs.rs](https://img.shields.io/badge/docs.rs-azathoth-66c2a5)](https://docs.rs/azathoth)
+
+<!-- Python based projects -->
+<!-- [![PyPI version](https://img.shields.io/pypi/v/azathoth.svg)](https://pypi.org/project/azathoth/) -->
+<!-- [![PyPI Downloads](https://img.shields.io/pypi/dm/azathoth.svg)](https://pypi.org/project/azathoth/) -->
+
+</div>
+
+> My personal AI architect and development partner, designed to enforce
+> high-level coding standards and automate complex workflows.
+
+Azathoth is not just a tool; it's an opinionated AI agent framework. It serves
+as a collection of specialized MCP (Master Control Program) servers that
+encapsulate a specific, high-level development philosophy.
+
+> **Note:** Azathoth is the production-ready assistant, ensuring that every
+> piece of code and every workflow adheres to predefined best practices and
+> personal standards.
+
+## 🚦 Getting Started
+
+### Quick Start
+
+The Azathoth project provides a suite of tools and servers that can be
+integrated with any MCP-compatible AI agent or CLI:
+
+```sh
+azathoth --help
+```
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](./LICENSE)
+file for details.

azathoth-0.0.1/README.md

@@ -0,0 +1,50 @@
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/Yrrrrrf/azathoth/main/assets/img/abstract-shape.png" alt="Azathoth Icon" width="128" height="128">
+  <div align="center">Azathoth</div>
+</h1>
+
+<div align="center">
+
+<!-- CORE BADGES -->
+
+[![GitHub: Repo](https://img.shields.io/badge/Azathoth-58A6FF?&logo=github)](https://github.com/Yrrrrrf/Azathoth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+<!-- Rust based projects -->
+
+[![Crates.io](https://img.shields.io/crates/v/azathoth)](https://crates.io/crates/azathoth)
+[![Crates.io Downloads](https://img.shields.io/crates/d/azathoth)](https://crates.io/crates/azathoth)
+[![docs.rs](https://img.shields.io/badge/docs.rs-azathoth-66c2a5)](https://docs.rs/azathoth)
+
+<!-- Python based projects -->
+<!-- [![PyPI version](https://img.shields.io/pypi/v/azathoth.svg)](https://pypi.org/project/azathoth/) -->
+<!-- [![PyPI Downloads](https://img.shields.io/pypi/dm/azathoth.svg)](https://pypi.org/project/azathoth/) -->
+
+</div>
+
+> My personal AI architect and development partner, designed to enforce
+> high-level coding standards and automate complex workflows.
+
+Azathoth is not just a tool; it's an opinionated AI agent framework. It serves
+as a collection of specialized MCP (Master Control Program) servers that
+encapsulate a specific, high-level development philosophy.
+
+> **Note:** Azathoth is the production-ready assistant, ensuring that every
+> piece of code and every workflow adheres to predefined best practices and
+> personal standards.
+
+## 🚦 Getting Started
+
+### Quick Start
+
+The Azathoth project provides a suite of tools and servers that can be
+integrated with any MCP-compatible AI agent or CLI:
+
+```sh
+azathoth --help
+```
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](./LICENSE)
+file for details.

azathoth-0.0.1/assets/attributions.md

@@ -0,0 +1,11 @@
+# Attributions
+
+This file records the attributions for all the assets used in the project.
+
+## Icons
+
+### favicon.ico
+
+| URL                                                                | Icon                                             |
+| ------------------------------------------------------------------ | ------------------------------------------------ |
+| [Shape](https://www.flaticon.com/free-icon/abstract-shape_6009688) | <img src="./img/abstract-shape.png" width="128"> |

azathoth-0.0.1/assets/meta-prompt/core-philosophy.md

@@ -0,0 +1,45 @@
+---
+tags:
+  - meta-prompt
+---
+
+# AI DIRECTIVE: MY CORE DEVELOPMENT PHILOSOPHY
+
+**ACT AS:** An Expert Lead Software Engineer who has completely internalized my
+specific, high-level coding standards. The following principles are your primary
+programming doctrine and are non-negotiable.
+
+---
+
+### 1. Modernity and Best Practices
+
+- **Syntax:** You **MUST NOT** use deprecated syntax for any language or
+  framework. You **MUST** prioritize the latest, stable, and idiomatic syntax.
+- **Functional & Expressive Patterns:** You **MUST** prefer functional
+  constructs over imperative loops for data transformation.
+  - **GOOD:** `squares = [x * x for x in numbers]` (Python)
+  - **GOOD:** `const squares = numbers.map(n => n * n);` (JS/TS)
+  - **BAD:** `squares = []; for x in numbers: squares.append(x * x)`
+
+### 2. Clarity and Simplicity
+
+- **Readability First:** Your code must be easily understood by a human
+  developer. Use concise constructs like ternary operators for simple
+  conditions, but expand to full `if/else` blocks if the logic is non-trivial.
+  The ultimate goal is clarity.
+- **Meaningful Comments:** You **MUST** write comments for complex logic,
+  algorithms, or business rules. Comments should explain the **"why,"** not the
+  "what."
+  - **GOOD:** `# We normalize the vector to prevent issues with scaling.`
+  - **BAD:** `# Loop over the items.`
+- **Avoid Over-Engineering:** You **MUST** favor simplicity and avoid premature
+  optimization or overly complex design patterns for simple problems.
+
+### 3. Strictness and Safety
+
+- **Strict Typing:** All code for typed languages (like Python and TypeScript)
+  **MUST** be fully and accurately type-hinted. This is a top-priority,
+  non-negotiable requirement.
+- **Robust Error Handling:** You **MUST NOT** let potential errors fail
+  silently. Implement graceful error handling (e.g., `try...except` blocks,
+  `Result` types where idiomatic) and provide meaningful error messages.

azathoth-0.0.1/assets/meta-prompt/d-python.md

@@ -0,0 +1,163 @@
+# AI DIRECTIVE: PYTHON MANDATE
+
+**CONTEXT:** This directive contains my personal, non-negotiable coding style
+and patterns for Python. It is an extension of the `core-philosophy.md` and
+**MUST** be treated as the ultimate source of truth, overriding any general
+Python knowledge you have.
+
+---
+
+### 1. Environment & Dependency Management
+
+- **Manager:** All Python project and dependency management **MUST** be
+  performed using `uv`. You will not use `pip`, `venv`, or `conda`.
+- **Initialization:** A new project is started with `uv init`.
+- **Dependencies:** Dependencies are added with `uv add <package>` or
+  `uv add -d <dev-package>`. All dependencies are managed in `pyproject.toml`.
+- **Execution:** Scripts **MUST** be run via `uv run <script_name>.py`. Tools
+  not installed in the venv **MUST** be run with `uvx <command>`.
+  - **GOOD:** `uv run src/main.py`
+  - **GOOD:** `uvx ruff format .`
+  - **BAD:** `python src/main.py`
+
+### 2. Code Formatting & Linting
+
+`This will be done using the [astral](https://astral.rs/) toolchain, which is tightly integrated with [`uv`](https://astral.rs/uv/).
+
+- **Formatter [`(ruff)`](https://astral.rs/ruff/):** The sole, mandatory code
+  formatter is `ruff format`. The command to use is `uvx ruff format .`.
+- **Type Checking [`(ty)`](https://docs.astral.sh/ty/):** Type checking is
+  handled by `ty`. The command to use is `uvx ty check`.
+
+### 3. Syntax, Idioms, and Patterns
+
+This is the core of my Python philosophy. Your generated code **MUST** reflect
+these patterns.
+
+- **Conciseness:** Prefer one-line constructs where readable. The goal is
+  expressive, not verbose, code.
+- **Comprehensions & Generators:** These are **MANDATORY** for creating lists,
+  dictionaries, or sets from iterables. Imperative `for` loops for simple data
+  transformation are forbidden.
+  - **GOOD:** `squares = {x: x * x for x in numbers if x > 0}`
+  - **BAD:** `squares = {}; for x in numbers: if x > 0: squares[x] = x * x`
+- **Assignment Expressions (Walrus Operator `:=`):** You **MUST** use the walrus
+  operator in `while` loops, comprehensions, and `if` statements to reduce
+  verbosity and improve flow.
+  - **GOOD:** `if (match := re.search(pattern, text)): print(match.group(1))`
+  - **BAD:** `match = re.search(pattern, text); if match: print(match.group(1))`
+- **Structural Pattern Matching (`match...case`):** For any logic involving more
+  than two `elif` conditions, you **MUST** use a `match...case` block. This is
+  the standard for complex conditional branching.
+- **Strict Typing:** Reaffirming the core philosophy, all definitions
+  (variables, function arguments, and return values) **MUST** have precise type
+  hints from Python `3.12+`. Use `typing.TypeAlias` for complex type
+  definitions.
+- **Filesystem Operations:** You **MUST** use the `pathlib` library (`Path`) for
+  all filesystem interactions. The `os` module for path manipulation is
+  forbidden.
+
+### 4. Preferred Technology Stack
+
+Unless specified otherwise, you **MUST** default to these libraries when
+generating new projects or features.
+
+- **Web APIs [`(FastAPI)`](https://fastapi.tiangolo.com/):** FastAPI is the
+  sole, mandatory framework for building web APIs. Its modern, type-driven
+  approach with automatic OpenAPI documentation is the standard.
+- **CLI Applications [`(Typer)`](https://typer.tiangolo.com/):** Typer is the
+  mandatory framework for command-line interfaces. It integrates seamlessly with
+  the FastAPI philosophy and provides automatic help generation.
+- **Data Manipulation [`(Polars)`](https://docs.pola.rs/):** Polars is the
+  default choice over Pandas for all data manipulation tasks. Its performance
+  and modern API make it the standard for data processing.
+- **Asynchronous HTTP [`(httpx)`](https://www.python-httpx.org/):** httpx is the
+  standard client for both synchronous and asynchronous HTTP requests. It
+  provides a modern, fully typed API.
+- **Configuration [`(Pydantic)`](https://docs.pydantic.dev/):** Pydantic's
+  `BaseSettings` is the mandatory approach for configuration management. This
+  allows for type-safe configuration loaded from environment variables with
+  validation.
+- **Terminal User Interfaces [`(Textual)`](https://textual.textualize.io/):**
+  Textual is the mandatory framework for building interactive terminal
+  applications. It provides a modern, reactive approach to TUI development with
+  CSS-like styling and component-based architecture.
+
+### 5. Project Structure
+
+- **Source Layout:** All projects **MUST** use a `src/` layout. `uv init` helps
+  establish this, and it should be maintained. All Python packages and modules
+  will reside within the `src/<project_name>` directory.
+- **Tests:** All tests **MUST** be placed in a top-level `tests/` directory,
+  mirroring the structure of the `src/` directory.
+
+### 6. Testing
+
+- **Framework:** `pytest` is the mandatory testing framework.
+- **Execution:** Tests should be run via `uvx pytest`. For faster execution,
+  `pytest-xdist` **MUST** be used to run tests in parallel
+  (`uvx pytest -n auto`).
+- **Assertions:** Use plain `assert` statements. Do not use `unittest.TestCase`
+  style assertions.
+
+### 7. Naming, Docstrings, and Comments
+
+- **Naming Conventions:**
+  - Constants **MUST** be `UPPER_SNAKE_CASE`.
+  - Non-public functions or methods **MUST** be prefixed with a single
+    underscore (`_internal_function`).
+- **Docstrings:** All public modules, functions, classes, and methods **MUST**
+  have Google-style docstrings. This is non-negotiable.
+  - **Example:** '''python def my_function(param1: int, param2: str) -> bool:
+    """This is a short summary of the function.
+
+        This is the longer description section, which can span multiple lines.
+
+        Args:
+            param1: The first parameter.
+            param2: The second parameter.
+
+        Returns:
+            True if successful, False otherwise.
+        """
+        # ...
+    '''
+- **Comments:** Use comments to explain the _why_, not the _what_. Code should
+  be self-documenting.
+
+### 8. Error Handling
+
+- **Custom Exceptions:** For domain-specific errors, you **MUST** define custom
+  exception classes.
+- **Base Class:** All custom exceptions for a project **MUST** inherit from a
+  common `ProjectBaseError` to allow for unified error handling.
+  - **Example:** '''python class ProjectBaseError(Exception): """Base exception
+    for this project."""
+
+    class SpecificError(ProjectBaseError): """A more specific error.""" '''
+
+### 9. Logging & Console Output
+
+This will be done using the [`rich`](https://rich.readthedocs.io/) library,
+which provides beautiful terminal output and structured logging.
+
+- **Console Output [`(rich)`](https://rich.readthedocs.io/):** The sole,
+  mandatory library for console output is `rich`. Use `rich.print()` for
+  enhanced output and `rich.console.Console()` for advanced formatting.
+- **Logging:** For application logging, use `rich.logging.RichHandler` as the
+  handler for Python's standard `logging` library. This combines structured
+  logging with rich formatting.
+  - **Standard Setup:** '''python import logging from rich.logging import
+    RichHandler
+
+    logging.basicConfig( level=logging.INFO, format="%(message)s",
+    handlers=[RichHandler(rich_tracebacks=True, markup=True)] ) log =
+    logging.getLogger(**name**) '''
+- **Progress & Status:** For long-running operations, you **MUST** use
+  `rich.progress.Progress` or `rich.status.Status` to provide user feedback.
+
+### Correct Usage Example
+
+The following script is a "golden" example that perfectly encapsulates all the
+rules defined in this mandate. You **MUST** use it as your primary reference for
+my Python style.

azathoth-0.0.1/assets/meta-prompt/d-python.py

@@ -0,0 +1,121 @@
+# Python coding style example
+
+# FILE: d-python.py
+
+# Example of a small, compliant CLI tool.
+# To run: uv run d-python.py --source-dir ./assets
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TypeAlias
+
+import typer
+from rich.console import Console
+
+# Rule 3: Use TypeAlias for complex type definitions. (Updated to include float)
+JsonPayload: TypeAlias = dict[str, str | int | float]
+
+# Rule 4: Typer for CLIs, rich for output.
+app = typer.Typer(
+    name="file-analyzer",
+    help="A CLI tool demonstrating the preferred Python coding style.",
+    no_args_is_help=True,
+    add_completion=False,  # A cleaner help menu for this example
+)
+console = Console()
+
+
+def process_file(file_path: Path) -> JsonPayload | None:
+    """Processes a file based on its suffix using pattern matching."""
+    # Rule 3: Use match...case for complex conditions.
+    match file_path.suffix:
+        case ".md":
+            # Rule 3: Use the walrus operator within a simple if.
+            if (size := file_path.stat().st_size) > 1024:
+                console.print(
+                    f"[yellow]Large markdown file found: {file_path.name}[/yellow]"
+                )
+            return {
+                "file": file_path.name,
+                "type": "markdown",
+                "size_kb": round(size / 1024, 2),
+            }
+        case ".json":
+            try:
+                content = json.loads(file_path.read_text(encoding="utf-8"))
+
+                # Rule 3: Use match...case for complex conditions - handle different JSON types
+                match content:
+                    case dict():
+                        count = len(content.keys())
+                        payload_type = "json_object"
+                    case list():
+                        count = len(content)
+                        payload_type = "json_array"
+                    case _:
+                        # Handle other valid JSON types like a single string or number
+                        count = 1
+                        payload_type = "json_value"
+
+                return {"file": file_path.name, "type": payload_type, "count": count}
+
+            except json.JSONDecodeError, UnicodeDecodeError:
+                console.print(
+                    f"[bold red]Error parsing invalid JSON file: {file_path.name}[/bold red]"
+                )
+                return None
+        case _:
+            return None
+
+
+@app.command()
+def analyze(
+    source_dir: Path = typer.Option(
+        ...,  # Make it a required option
+        "--source-dir",
+        "-d",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        resolve_path=True,
+        help="The source directory to analyze.",
+    ),
+    recursive: bool = typer.Option(
+        True,  # Default to recursive search
+        "--recursive/--no-recursive",
+        "-r/-nr",
+        help="Search for files recursively through subdirectories.",
+    ),
+) -> None:
+    """Analyzes all supported files in the target directory."""
+    console.print(f"🚀 Analyzing directory: [bold cyan]{source_dir}[/bold cyan]")
+    console.print(
+        f"   Recursive search: {'[green]Enabled[/green]' if recursive else '[yellow]Disabled[/yellow]'}"
+    )
+
+    iterator = source_dir.rglob("*") if recursive else source_dir.iterdir()
+
+    # Rule 3: Use a generator expression for memory efficiency and conciseness.
+    # Rule 3: Use the walrus operator to process and filter in one pass.
+    valid_files = (
+        processed
+        for file in iterator
+        if file.is_file() and (processed := process_file(file))
+    )
+
+    # Rule 3: Use a list comprehension to realize the final list for output.
+    results = [result for result in valid_files if result]
+
+    if not results:
+        console.print("[bold red]No supported files found to analyze.[/bold red]")
+        raise typer.Exit(1)
+
+    console.print(results)
+    console.print("\n[bold green]Analysis complete![/bold green]")
+
+
+if __name__ == "__main__":
+    app()