aihawk 0.1.0__tar.gz

aihawk-0.1.0/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone.
+
+## Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported by contacting the maintainer at **federico.elia.majo@gmail.com**. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+
+The maintainer is obligated to maintain confidentiality with regard to the reporter of an incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

aihawk-0.1.0/.github/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing to AIHawk
+
+Thanks for being here. This page says what this repository is, so you can tell in
+one minute whether your change belongs here or in one of the packages below.
+
+## What lives here
+
+The `aihawk` package: the two-pane interface, the loop that turns a sentence into
+browser actions, and the command line around both. If you are changing what a
+person sees, or how the model decides what to do next, it is here.
+
+What is NOT here is the browser. AIHawk does not drive Firefox directly - it
+talks to an MCP server over MCP, using the same fourteen tools any other client
+gets. That is deliberate and it is the thing to understand before changing
+anything: this interface has no privileged path to the page, so a browser
+capability it needs is a capability every client gets, or it does not exist.
+
+This page said the opposite earlier on 2 September 2026, when the repository held
+only documentation. The package moved in the same day.
+
+## Where the code is
+
+| Repository | What it holds |
+|---|---|
+| **this one** | the interface, the agent loop, the CLI |
+| [invisible-playwright-mcp](https://github.com/feder-cr/invisible-playwright-mcp) | the MCP server: the fourteen tools, and nothing with a face |
+| [invisible_playwright](https://github.com/feder-cr/invisible_playwright) | the Python wrapper, the launcher, and the patched browser it pins |
+| [invisible_core](https://github.com/feder-cr/invisible_core) | seed to fingerprint to preferences, proxy and geolocation |
+
+Where things go:
+
+- the page, the conversation, the step list, the model's behaviour: **here**
+- a tool that returns the wrong thing, or a click that does not land: **the MCP server**
+- the browser failing to start, a proxy not used, a timezone that does not match
+  the exit country: **the wrapper or the core**
+- a detector spotting the browser: almost always the engine, not this repository
+
+If you are not sure, open the issue here and it will be moved.
+
+## Development setup
+
+```bash
+git clone https://github.com/feder-cr/AIHawk.git
+cd AIHawk
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[test]"
+```
+
+Python 3.11 or newer, Windows or Linux. No key is needed to work on it: `aihawk
+ui` without one runs the literal-command placeholder, which drives the real
+browser through the real server and is how most of this was tested.
+
+## Running the tests
+
+```bash
+pytest                 # the default selection, no browser, seconds
+pytest -m ui           # drives a REAL browser through a REAL server
+```
+
+The `ui` tests are deselected by default because they are slow and they must run
+serially: they launch a browser, and two browser benches on one machine produce
+results that are noise with numbers on them. Run them one at a time, on a machine
+that is not doing anything else.
+
+They assert what happened INSIDE the page, never what a tool said about itself. A
+tool that answers "clicked #go" while nothing moved is the failure they exist to
+catch, so the tool's own success string is never the assertion.
+
+## Pull requests
+
+Fork, branch, open the pull request against `main`. There is one branch and no
+release train.
+
+Keep a pull request to one change, and say in the description what a reader would
+be able to do afterwards that they could not do before. If you change what the
+interface shows, include a screenshot: this project has already had the case
+where five green tests passed while the pane showed a black rectangle, and the
+picture was the only thing that noticed.
+
+## Opening an issue
+
+Use one of the [templates](https://github.com/feder-cr/AIHawk/issues/new/choose).
+Before you do, search the open and closed issues.
+
+For a bug, the two things that decide how fast it can be answered are the exact
+commands you ran and what happened instead of what you expected. Include your OS
+and Python version, and whether you were running `ui` or `do`.
+
+Please do not report a security problem in a public issue. In particular, never
+paste an OpenRouter key into one: if you have, rotate it before anything else.
+
+## Tone
+
+Questions are welcome and beginners are welcome. If something in the README was
+not clear enough for you, that is worth an issue on its own, because it was
+probably not clear to somebody else either.
+
+## Licence
+
+By contributing you agree that your contribution is licensed under the MIT
+licence, which is the licence in [LICENSE](../LICENSE). Everything received
+before 2 September 2026 was contributed under AGPL-3.0 and stays under it: a
+licence already granted is not withdrawn by changing that file.
+
+Participation is covered by the [Code of Conduct](CODE_OF_CONDUCT.md).

aihawk-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: feder-cr

aihawk-0.1.0/.github/ISSUE_TEMPLATE/bug-issue.yml

@@ -0,0 +1,90 @@
+name: Bug report
+description: Report a bug or an issue that isn't working as expected.
+title: "[BUG]: <Provide a clear, descriptive title>"
+labels: ["bug"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please fill out the following information to help us resolve the issue.
+
+  - type: input
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+      placeholder: "Describe the bug in detail..."
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: |
+        Steps to reproduce the behavior:
+        1. Use branch named '...'
+        2. Go to file '...'
+        3. Find property named '...'
+        4. Change '...'
+        5. Run program using command '...'
+        6. See error
+      placeholder: "List the steps to reproduce the bug..."
+
+  - type: input
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+      placeholder: "What was the expected result?"
+
+  - type: input
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened instead.
+      placeholder: "What happened instead?"
+
+  - type: dropdown
+    id: branch
+    attributes:
+      label: Branch
+      description: Specify the branch you were using when the bug occurred.
+      options:
+        - main
+        - other
+
+  - type: input
+    id: otherBranch
+    attributes:
+      label: Branch name
+      description: If you selected ```other``` branch for the previous question, what is the branch name?
+      placeholder: "what-is-the-name-of-the-branch-you-were-using"
+
+  - type: input
+    id: pythonVersion
+    attributes:
+      label: Python version
+      description: Specify the version of Python you were using when the bug occurred.
+      placeholder: "e.g., 3.12.5(64b)"
+
+  - type: input
+    id: llm
+    attributes:
+      label: LLM Used
+      description: Specify the LLM provider you were using when the bug occurred.
+      placeholder: "e.g., ChatGPT"
+
+  - type: input
+    id: model
+    attributes:
+      label: Model used
+      description: Specify the LLM model you were using when the bug occurred.
+      placeholder: "e.g., GPT-4o-mini"
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any other context about the problem here.
+      placeholder: "Any additional information..."

aihawk-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions
+    url: https://t.me/AIhawkCommunity
+    about: You can join the discussions on Telegram.
+  - name: Contributing guide
+    url: https://github.com/feder-cr/AIHawk/blob/main/.github/CONTRIBUTING.md
+    about: Which repository your issue belongs in, and what to include.

aihawk-0.1.0/.github/ISSUE_TEMPLATE/documentation-issue.yml

@@ -0,0 +1,39 @@
+name: Documentation request
+description: Suggest improvements or additions to the project's documentation.
+title: "[DOCS]: <Provide a short title>"
+labels: ["documentation"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping to improve the project's documentation! Please provide the following details to ensure your request is clear.
+
+  - type: input
+    id: doc_section
+    attributes:
+      label: Affected documentation section
+      description: Specify which part of the documentation needs improvement or addition.
+      placeholder: "e.g., Installation Guide, API Reference..."
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Documentation improvement description
+      description: Describe the specific improvements or additions you suggest.
+      placeholder: "Explain what changes you propose and why..."
+
+  - type: input
+    id: reason
+    attributes:
+      label: Why is this change necessary?
+      description: Explain why the documentation needs to be updated or expanded.
+      placeholder: "Describe the issue or gap in the documentation..."
+
+  - type: input
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any other context, such as related documentation, external resources, or screenshots.
+      placeholder: "Add any other supporting information..."

aihawk-0.1.0/.github/ISSUE_TEMPLATE/enhancement-issue.yml

@@ -0,0 +1,46 @@
+name: Feature request
+description: Suggest a new feature or improvement for the project.
+title: "[FEATURE]: <Provide a descriptive title>"
+labels: ["enhancement"]
+assignees: []
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting a feature! Please fill out the form below to help us understand your idea.
+
+  - type: input
+    id: summary
+    attributes:
+      label: Feature summary
+      description: Provide a short summary of the feature you're requesting.
+      placeholder: "Summarize the feature in a few words..."
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: A detailed description of the feature or improvement.
+      placeholder: "Describe the feature in detail..."
+
+  - type: input
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Explain why this feature would be beneficial and how it solves a problem.
+      placeholder: "Why do you need this feature?"
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: List any alternative solutions or features you've considered.
+      placeholder: "Are there any alternative features or solutions you’ve considered?"
+
+  - type: input
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots to support your feature request.
+      placeholder: "Any additional information..."

aihawk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  # This repository is public and everything in it is English by rule. The gate
+  # is a COPY and not a reference to the one in the sibling packages, on purpose:
+  # it scans the tree it is run from, and running a sibling's copy from here
+  # silently scans the wrong repository and reports clean. That happened once
+  # already, which is why each package carries its own.
+  english:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: the repository is English
+        run: |
+          python scripts/check_english_only.py --selftest
+          python scripts/check_english_only.py
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: install and test
+        # The default selection excludes `ui`, which drives a real browser: those
+        # need an engine download and a machine doing nothing else, and a runner
+        # is neither. They are run by hand, serially, before a release.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+          python -m pytest -q
+
+  # This package is published, so the thing that must work is the WHEEL, not the
+  # checkout. An editable install can pass every test while the built artifact is
+  # missing a module: the tests import from src/ either way, and only a clean
+  # install from the wheel can tell the difference.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: the wheel builds, installs clean, and answers
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build --wheel
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl
+          /tmp/clean/bin/aihawk --help
+          /tmp/clean/bin/python -c "import aihawk.web, aihawk.brain, aihawk.link, aihawk.cli"

aihawk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,109 @@
+name: publish
+
+# Publish `aihawk` from a tag via PyPI Trusted Publishing (OIDC), with no
+# long-lived token anywhere. The trust lives in the `pypi` GitHub Environment,
+# minted per run and valid for minutes. Only the `upload` job names that
+# environment, and it declares `needs: gate`, so a red gate means the only job
+# that can authenticate never starts.
+#
+# BEFORE THE FIRST RUN, on PyPI: the name is unregistered, so Your projects will
+# not list it. Use Account -> Publishing -> Add a pending publisher with:
+#   PyPI Project Name: aihawk
+#   Owner:             feder-cr
+#   Repository name:   AIHawk
+#   Workflow name:     publish.yml
+#   Environment name:  pypi
+# Until that exists the upload fails with `invalid-publisher`, which is the
+# correct failure: nothing has said this workflow may speak for this project.
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  already-published:
+    runs-on: ubuntu-latest
+    outputs:
+      present: ${{ steps.probe.outputs.present }}
+      version: ${{ steps.probe.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: probe
+        shell: bash
+        # Asks the INDEX, not the ledger and not the tag: a re-pushed tag or a
+        # backfill is then a logged no-op rather than a red run, and the only
+        # answer that stops everything is one that is neither yes nor no.
+        run: |
+          VERSION="$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          CODE=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/aihawk/$VERSION/json")
+          case "$CODE" in
+            200) echo "present=yes" >> "$GITHUB_OUTPUT"
+                 echo "::notice::aihawk $VERSION is already on the index. No-op, not a failure." ;;
+            404) echo "present=no"  >> "$GITHUB_OUTPUT" ;;
+            *)   echo "the index answered $CODE for $VERSION, which is neither present nor absent. Refusing rather than guessing." >&2
+                 exit 1 ;;
+          esac
+
+  gate:
+    needs: already-published
+    if: needs.already-published.outputs.present != 'yes'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: the tag names the version being built
+        if: github.event_name == 'push'
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          HAVE="${{ needs.already-published.outputs.version }}"
+          if [ "$TAG" != "$HAVE" ]; then
+            echo "tag v$TAG does not name the version in pyproject.toml ($HAVE)" >&2
+            exit 1
+          fi
+      - name: install and run the suite
+        # A tag push does not trigger the ordinary test workflow, which runs on
+        # branches and pull requests, so without this a tag could publish code
+        # that no job has ever run.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+          python -m pytest -q
+      - name: the wheel installs into an empty environment and answers
+        # The published artifact is a wheel, and the suite above imports from
+        # src/ either way. Only a clean install can tell you that the thing
+        # about to reach users actually starts.
+        run: |
+          pip install build
+          python -m build --wheel
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl
+          /tmp/clean/bin/aihawk --help
+
+  upload:
+    needs: [already-published, gate]
+    if: needs.already-published.outputs.present != 'yes'
+    runs-on: ubuntu-latest
+    environment: pypi          # the OIDC trust relationship lives HERE, behind the gate
+    permissions:
+      id-token: write          # trusted publishing; no token in a secret anywhere
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - name: twine check
+        run: |
+          pip install twine
+          twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1

aihawk-0.1.0/.github/workflows/stale.yml

@@ -0,0 +1,42 @@
+name: Mark and Close Stale Issues
+
+on:
+  # Schedule the workflow to run periodically (e.g., daily at 1:30 AM UTC)
+  schedule:
+    - cron: "30 1 * * *"
+  workflow_dispatch:
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Run Stale Action
+        uses: actions/stale@v9
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          days-before-issue-stale: 10 # Days of inactivity before marking an issue as stale
+          days-before-issue-close: 5 # Days after being marked stale before closing the issue
+          stale-issue-label: "stale" # Label to apply to stale issues
+          exempt-issue-labels: "pinned,important" # Labels to exclude from being marked as stale
+          exempt-issue-assignees: true # Exempt issues with assignees from being marked as stale
+          stale-issue-message: "This issue has been marked as stale due to inactivity. Please comment or update if this is still relevant."
+          close-issue-message: "This issue was closed due to prolonged inactivity."
+          days-before-pr-stale: 10 # Days of inactivity before marking a PR as stale
+          days-before-pr-close: 2 # Days after being marked stale before closing the PR
+          stale-pr-label: "stale" # Label to apply to stale PRs
+          exempt-pr-labels: "pinned,important" # Labels to exclude from being marked as stale
+          stale-pr-message: >
+            "This pull request has been marked as stale due to inactivity. 
+            To keep it open, you can:
+            - Show progress by updating the PR with new commits.
+            - Continue the conversation by adding comments or requesting clarification on any blockers.
+            - Resolve pending feedback by replying to unresolved comments or implementing suggested changes.
+            - Indicate readiness for review by explicitly requesting a review from maintainers or reviewers.
+            If no action is taken within 7 days, this pull request will be closed."
+          close-pr-message: "This PR was closed due to prolonged inactivity."
+          remove-stale-when-updated: true # Remove the stale label if there is new activity
+          operations-per-run: 20 # Number of issues to process per run (default is 30)