agentyc 0.1.0__tar.gz

agentyc-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# Cache files
+.DS_Store
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.ipynb_checkpoints
+~/
+
+# Virtual Environments
+.venv*
+venv/
+
+# IDEs
+.vscode/
+.idea/
+
+# Build files
+dist/
+
+# Data files
+*.gif
+*.txt
+*.pdf
+*.csv
+*.json
+*.jsonl
+*.log
+*.bak
+
+# Secrets and sensitive files
+secrets.env
+.env
+browser_cookies.json
+cookies.json
+gcp-login.json
+saved_trajectories/
+old_tests/
+AgentHistory.json
+AgentHistoryList.json
+private_example.py
+private_example
+CLAUDE.local.md
+
+uv.lock
+temp
+tmp
+
+# Google API credentials
+credentials.json
+token.json
+
+!docs/docs.json
+
+
+temp-profile-*
+
+screenshot.png
+
+# *.md
+
+all_github_issues_progress.md
+all_github_issues.md
+
+todo-input-token.md
+
+TOOL_CHANGES_SUMMARY.md
+
+
+claude-code-todo
+result_judge.md
+result.md
+result2.md
+result3.md
+Brainstorm.md
+example.ipynb
+*SUMMARY.md
+todo.md
+product_extraction.ipynb
+product_extraction.py
+*report.md
+plot.py
+
+.claude/

agentyc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Gregor Zunic
+
+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.

agentyc-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: agentyc
+Version: 0.1.0
+Summary: Deterministic MCP-first browser automation runtime for coding agents
+Project-URL: Homepage, https://github.com/distillation-labs/agentyc
+Project-URL: Documentation, https://github.com/distillation-labs/agentyc/tree/main/docs
+Project-URL: Repository, https://github.com/distillation-labs/agentyc
+Project-URL: Source, https://github.com/distillation-labs/agentyc
+Project-URL: Issues, https://github.com/distillation-labs/agentyc/issues
+Project-URL: Changelog, https://github.com/distillation-labs/agentyc/releases
+Author: Gregor Zunic
+License-File: LICENSE
+Keywords: browser-automation,cdp,chromium,coding-agents,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.11
+Requires-Dist: aiohttp==3.13.4
+Requires-Dist: anthropic==0.76.0
+Requires-Dist: anyio==4.12.1
+Requires-Dist: bubus==1.5.6
+Requires-Dist: cdp-use==1.4.5
+Requires-Dist: google-api-core==2.29.0
+Requires-Dist: google-api-python-client==2.188.0
+Requires-Dist: google-auth-oauthlib==1.2.4
+Requires-Dist: google-auth==2.48.0
+Requires-Dist: google-genai==1.65.0
+Requires-Dist: groq==1.0.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: markdownify==1.2.2
+Requires-Dist: mcp==1.26.0
+Requires-Dist: ollama==0.6.1
+Requires-Dist: openai==2.16.0
+Requires-Dist: pillow==12.2.0
+Requires-Dist: posthog==7.7.0
+Requires-Dist: psutil==7.2.2
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: pyobjc==12.1; platform_system == 'darwin'
+Requires-Dist: pyotp==2.9.0
+Requires-Dist: pypdf==6.10.2
+Requires-Dist: python-docx==1.2.0
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: reportlab==4.4.9
+Requires-Dist: requests==2.33.0
+Requires-Dist: screeninfo==0.8.1; platform_system != 'darwin'
+Requires-Dist: typing-extensions==4.15.0
+Requires-Dist: uuid7==0.1.0
+Provides-Extra: all
+Requires-Dist: boto3==1.42.37; extra == 'all'
+Requires-Dist: oci==2.166.0; extra == 'all'
+Provides-Extra: aws
+Requires-Dist: boto3==1.42.37; extra == 'aws'
+Provides-Extra: copilot
+Requires-Dist: github-copilot-sdk<0.2.0,>=0.1.0; extra == 'copilot'
+Provides-Extra: eval
+Requires-Dist: anyio==4.12.1; extra == 'eval'
+Requires-Dist: datamodel-code-generator==0.53.0; extra == 'eval'
+Requires-Dist: lmnr[all]==0.7.42; extra == 'eval'
+Requires-Dist: psutil==7.2.2; extra == 'eval'
+Provides-Extra: oci
+Requires-Dist: oci==2.166.0; extra == 'oci'
+Provides-Extra: video
+Requires-Dist: imageio[ffmpeg]==2.37.2; extra == 'video'
+Requires-Dist: numpy==2.4.1; extra == 'video'
+Description-Content-Type: text/markdown
+
+# agentyc
+
+Deterministic, MCP-first browser automation for coding agents.
+
+`agentyc` ships a public stdio MCP server for Chrome or Chromium automation plus the Python session primitives that back that server. The public contract is centered on deterministic browser control, token-aware state snapshots, and deterministic extraction without LLM fallback.
+
+## What It Is
+
+- Public stdio MCP server exposed by the `agentyc` console script.
+- Browser control over CDP through `agentyc.mcp.server`, `agentyc.tools.service`, `agentyc.mcp.state`, and `agentyc.browser.session`.
+- Deterministic extraction routes in `agentyc.tools.extraction.router` for common page structures.
+- Python imports such as `AgentycServer`, `BrowserSession`, `BrowserProfile`, and `Tools` for direct embedding.
+
+The default MCP path does not require an API key for navigation, interaction, state inspection, screenshots, HTML access, cookies, or deterministic extraction.
+
+## Install
+
+```bash
+uv tool install agentyc
+```
+
+From source:
+
+```bash
+uv venv --python 3.11
+source .venv/bin/activate
+uv sync --dev
+```
+
+## Run The MCP Server
+
+Start the stdio MCP server:
+
+```bash
+agentyc
+```
+
+Equivalent explicit form:
+
+```bash
+agentyc mcp
+```
+
+Override the idle timeout for the browser session tracked by the server:
+
+```bash
+agentyc --session-timeout-minutes 20
+```
+
+Shared-browser collaboration flags are also available on `agentyc mcp` and the no-subcommand form:
+
+- `--runtime-label`
+- `--runtime-role`
+- `--parent-runtime-id`
+- `--shared-browser-mode`
+- `--shared-browser-window-bounds`
+- `--shared-browser-focus-policy`
+
+## Shared Browser Mode
+
+Launch a Chrome or Chromium instance with remote debugging enabled and print its CDP WebSocket URL:
+
+```bash
+agentyc browser --detach
+```
+
+Attach the MCP server to that browser instead of launching a separate browser process:
+
+```bash
+agentyc mcp --cdp-url ws://127.0.0.1:9222/devtools/browser/...
+```
+
+Current shared-browser behavior is intentionally narrow:
+
+- Each attached MCP server creates a collaboration target in the shared browser: a tab by default, or a separate window when `--shared-browser-mode window` is used.
+- Attach and `new_tab=true` flows update the runtime's focused target automatically.
+- Visible browser activation is controlled by `--shared-browser-focus-policy`: `preserve` avoids stealing the human-focused surface, while `activate` explicitly foregrounds the runtime target.
+- `browser_get_state` and `browser_list_tabs` surface ownership metadata, display titles, and optional window bounds for shared-browser targets.
+- Stock Chrome and CDP do not provide reliable per-tab color ownership cues.
+- Shared-browser workflows should be treated as best-effort collaboration, not hard isolation.
+
+## MCP Tool Surface
+
+Navigation and state:
+
+- `browser_navigate`
+- `browser_go_back`
+- `browser_go_forward`
+- `browser_refresh`
+- `browser_wait`
+- `browser_wait_for_network_idle`
+- `browser_get_state`
+- `browser_get_html`
+- `browser_screenshot`
+
+Interaction:
+
+- `browser_click`
+- `browser_right_click`
+- `browser_double_click`
+- `browser_hover`
+- `browser_drag_to`
+- `browser_type`
+- `browser_press_key`
+- `browser_scroll`
+- `browser_scroll_to_text`
+- `browser_select_option`
+- `browser_get_dropdown_options`
+- `browser_upload_file`
+
+Inspection and extraction:
+
+- `browser_extract_content`
+- `browser_find_elements`
+- `browser_search_page`
+- `browser_wait_for_element`
+- `browser_get_focused_element`
+- `browser_evaluate`
+
+Tabs, cookies, and session state:
+
+- `browser_list_tabs`
+- `browser_switch_tab`
+- `browser_close_tab`
+- `browser_get_cookies`
+- `browser_set_cookies`
+- `browser_clear_cookies`
+- `browser_save_state`
+- `browser_load_state`
+
+Observability and lifecycle:
+
+- `browser_get_console_logs`
+- `browser_get_network_log`
+- `browser_list_sessions`
+- `browser_close_session`
+- `browser_close_all`
+
+The public server exposes tools only. It does not publish MCP resources or prompts.
+
+## State And Element Targeting
+
+`browser_get_state` is the primary inspection primitive.
+
+- Stable element refs such as `e123` are derived from backend node ids.
+- `mode` supports `auto`, `full`, `min`, and `focus`.
+- `since_hash` allows unchanged-state checks without resending interactive element payloads.
+- Compact state payloads can surface `compaction_strategy`, truncation counts, ownership, and runtime metadata when relevant.
+- Screenshots are returned as MCP image content, with JSON metadata in a separate text payload.
+
+Prefer refs from `browser_get_state` over legacy numeric `index` arguments.
+
+## Deterministic Extraction
+
+`browser_extract_content` in the public MCP server is deterministic-only.
+
+- No LLM fallback is used in the public server.
+- Compatible routes include links, link collections, images, tables, lists, form fields, and key-value blocks.
+- `output_schema` is supported when the query matches a deterministic route.
+- Unsupported free-form requests return an explicit error instead of silently degrading.
+- Responses include `<extraction_metadata>` describing the route and truncation state.
+
+This means the default extraction path works without any API key.
+
+## Python Surface
+
+The package also exposes Python imports for direct integration:
+
+```python
+from agentyc import AgentycServer, BrowserProfile, BrowserSession, Tools
+```
+
+The public product story is still MCP-first. Direct Python usage is available for embedding or lower-level control.
+
+## Development
+
+```bash
+./scripts/lint.sh
+./scripts/test.sh
+uv build
+```
+
+## Docs
+
+- `docs/overview.md`
+- `docs/features.md`
+- `docs/architecture.md`
+- `docs/api.md`
+- `docs/configuration.md`
+- `docs/tech-stack.md`

agentyc-0.1.0/README.md

@@ -0,0 +1,190 @@
+# agentyc
+
+Deterministic, MCP-first browser automation for coding agents.
+
+`agentyc` ships a public stdio MCP server for Chrome or Chromium automation plus the Python session primitives that back that server. The public contract is centered on deterministic browser control, token-aware state snapshots, and deterministic extraction without LLM fallback.
+
+## What It Is
+
+- Public stdio MCP server exposed by the `agentyc` console script.
+- Browser control over CDP through `agentyc.mcp.server`, `agentyc.tools.service`, `agentyc.mcp.state`, and `agentyc.browser.session`.
+- Deterministic extraction routes in `agentyc.tools.extraction.router` for common page structures.
+- Python imports such as `AgentycServer`, `BrowserSession`, `BrowserProfile`, and `Tools` for direct embedding.
+
+The default MCP path does not require an API key for navigation, interaction, state inspection, screenshots, HTML access, cookies, or deterministic extraction.
+
+## Install
+
+```bash
+uv tool install agentyc
+```
+
+From source:
+
+```bash
+uv venv --python 3.11
+source .venv/bin/activate
+uv sync --dev
+```
+
+## Run The MCP Server
+
+Start the stdio MCP server:
+
+```bash
+agentyc
+```
+
+Equivalent explicit form:
+
+```bash
+agentyc mcp
+```
+
+Override the idle timeout for the browser session tracked by the server:
+
+```bash
+agentyc --session-timeout-minutes 20
+```
+
+Shared-browser collaboration flags are also available on `agentyc mcp` and the no-subcommand form:
+
+- `--runtime-label`
+- `--runtime-role`
+- `--parent-runtime-id`
+- `--shared-browser-mode`
+- `--shared-browser-window-bounds`
+- `--shared-browser-focus-policy`
+
+## Shared Browser Mode
+
+Launch a Chrome or Chromium instance with remote debugging enabled and print its CDP WebSocket URL:
+
+```bash
+agentyc browser --detach
+```
+
+Attach the MCP server to that browser instead of launching a separate browser process:
+
+```bash
+agentyc mcp --cdp-url ws://127.0.0.1:9222/devtools/browser/...
+```
+
+Current shared-browser behavior is intentionally narrow:
+
+- Each attached MCP server creates a collaboration target in the shared browser: a tab by default, or a separate window when `--shared-browser-mode window` is used.
+- Attach and `new_tab=true` flows update the runtime's focused target automatically.
+- Visible browser activation is controlled by `--shared-browser-focus-policy`: `preserve` avoids stealing the human-focused surface, while `activate` explicitly foregrounds the runtime target.
+- `browser_get_state` and `browser_list_tabs` surface ownership metadata, display titles, and optional window bounds for shared-browser targets.
+- Stock Chrome and CDP do not provide reliable per-tab color ownership cues.
+- Shared-browser workflows should be treated as best-effort collaboration, not hard isolation.
+
+## MCP Tool Surface
+
+Navigation and state:
+
+- `browser_navigate`
+- `browser_go_back`
+- `browser_go_forward`
+- `browser_refresh`
+- `browser_wait`
+- `browser_wait_for_network_idle`
+- `browser_get_state`
+- `browser_get_html`
+- `browser_screenshot`
+
+Interaction:
+
+- `browser_click`
+- `browser_right_click`
+- `browser_double_click`
+- `browser_hover`
+- `browser_drag_to`
+- `browser_type`
+- `browser_press_key`
+- `browser_scroll`
+- `browser_scroll_to_text`
+- `browser_select_option`
+- `browser_get_dropdown_options`
+- `browser_upload_file`
+
+Inspection and extraction:
+
+- `browser_extract_content`
+- `browser_find_elements`
+- `browser_search_page`
+- `browser_wait_for_element`
+- `browser_get_focused_element`
+- `browser_evaluate`
+
+Tabs, cookies, and session state:
+
+- `browser_list_tabs`
+- `browser_switch_tab`
+- `browser_close_tab`
+- `browser_get_cookies`
+- `browser_set_cookies`
+- `browser_clear_cookies`
+- `browser_save_state`
+- `browser_load_state`
+
+Observability and lifecycle:
+
+- `browser_get_console_logs`
+- `browser_get_network_log`
+- `browser_list_sessions`
+- `browser_close_session`
+- `browser_close_all`
+
+The public server exposes tools only. It does not publish MCP resources or prompts.
+
+## State And Element Targeting
+
+`browser_get_state` is the primary inspection primitive.
+
+- Stable element refs such as `e123` are derived from backend node ids.
+- `mode` supports `auto`, `full`, `min`, and `focus`.
+- `since_hash` allows unchanged-state checks without resending interactive element payloads.
+- Compact state payloads can surface `compaction_strategy`, truncation counts, ownership, and runtime metadata when relevant.
+- Screenshots are returned as MCP image content, with JSON metadata in a separate text payload.
+
+Prefer refs from `browser_get_state` over legacy numeric `index` arguments.
+
+## Deterministic Extraction
+
+`browser_extract_content` in the public MCP server is deterministic-only.
+
+- No LLM fallback is used in the public server.
+- Compatible routes include links, link collections, images, tables, lists, form fields, and key-value blocks.
+- `output_schema` is supported when the query matches a deterministic route.
+- Unsupported free-form requests return an explicit error instead of silently degrading.
+- Responses include `<extraction_metadata>` describing the route and truncation state.
+
+This means the default extraction path works without any API key.
+
+## Python Surface
+
+The package also exposes Python imports for direct integration:
+
+```python
+from agentyc import AgentycServer, BrowserProfile, BrowserSession, Tools
+```
+
+The public product story is still MCP-first. Direct Python usage is available for embedding or lower-level control.
+
+## Development
+
+```bash
+./scripts/lint.sh
+./scripts/test.sh
+uv build
+```
+
+## Docs
+
+- `docs/overview.md`
+- `docs/features.md`
+- `docs/architecture.md`
+- `docs/api.md`
+- `docs/configuration.md`
+- `docs/tech-stack.md`

agentyc-0.1.0/agentyc/__init__.py

@@ -0,0 +1,124 @@
+import os
+from asyncio import base_subprocess
+from typing import TYPE_CHECKING
+
+from agentyc.logging_config import setup_logging
+
+# Only set up logging if not in MCP mode or if explicitly requested
+if os.environ.get('AGENTYC_SETUP_LOGGING', 'true').lower() != 'false':
+	from agentyc.config import CONFIG
+
+	debug_log_file = getattr(CONFIG, 'AGENTYC_DEBUG_LOG_FILE', None)
+	info_log_file = getattr(CONFIG, 'AGENTYC_INFO_LOG_FILE', None)
+	logger = setup_logging(debug_log_file=debug_log_file, info_log_file=info_log_file)
+else:
+	import logging
+
+	logger = logging.getLogger('agentyc')
+
+_original_del = base_subprocess.BaseSubprocessTransport.__del__
+
+
+def _patched_del(self):
+	"""Avoid noisy RuntimeError when subprocess cleanup runs after loop shutdown."""
+	try:
+		if hasattr(self, '_loop') and self._loop and self._loop.is_closed():
+			return
+		_original_del(self)
+	except RuntimeError as e:
+		if 'Event loop is closed' not in str(e):
+			raise
+
+
+base_subprocess.BaseSubprocessTransport.__del__ = _patched_del
+
+
+if TYPE_CHECKING:
+	from agentyc.actions import ActionModel, ActionResult
+	from agentyc.browser import BrowserProfile, BrowserSession
+	from agentyc.browser import BrowserSession as Browser
+	from agentyc.dom.service import DomService
+	from agentyc.llm import models
+	from agentyc.llm.agentyc.chat import ChatAgentyc
+	from agentyc.llm.anthropic.chat import ChatAnthropic
+	from agentyc.llm.azure.chat import ChatAzureOpenAI
+	from agentyc.llm.copilot.chat import ChatGitHubCopilot
+	from agentyc.llm.google.chat import ChatGoogle
+	from agentyc.llm.groq.chat import ChatGroq
+	from agentyc.llm.litellm.chat import ChatLiteLLM
+	from agentyc.llm.mistral.chat import ChatMistral
+	from agentyc.llm.oci_raw.chat import ChatOCIRaw
+	from agentyc.llm.ollama.chat import ChatOllama
+	from agentyc.llm.openai.chat import ChatOpenAI
+	from agentyc.llm.vercel.chat import ChatVercel
+	from agentyc.mcp.server import AgentycServer
+	from agentyc.tools.service import Controller, Tools
+
+
+_LAZY_IMPORTS = {
+	'ActionModel': ('agentyc.actions', 'ActionModel'),
+	'ActionResult': ('agentyc.actions', 'ActionResult'),
+	'BrowserSession': ('agentyc.browser', 'BrowserSession'),
+	'Browser': ('agentyc.browser', 'BrowserSession'),
+	'BrowserProfile': ('agentyc.browser', 'BrowserProfile'),
+	'Tools': ('agentyc.tools.service', 'Tools'),
+	'Controller': ('agentyc.tools.service', 'Controller'),
+	'DomService': ('agentyc.dom.service', 'DomService'),
+	'ChatOpenAI': ('agentyc.llm.openai.chat', 'ChatOpenAI'),
+	'ChatGoogle': ('agentyc.llm.google.chat', 'ChatGoogle'),
+	'ChatAnthropic': ('agentyc.llm.anthropic.chat', 'ChatAnthropic'),
+	'ChatAgentyc': ('agentyc.llm.agentyc.chat', 'ChatAgentyc'),
+	'ChatGitHubCopilot': ('agentyc.llm.copilot.chat', 'ChatGitHubCopilot'),
+	'ChatGroq': ('agentyc.llm.groq.chat', 'ChatGroq'),
+	'ChatLiteLLM': ('agentyc.llm.litellm.chat', 'ChatLiteLLM'),
+	'ChatMistral': ('agentyc.llm.mistral.chat', 'ChatMistral'),
+	'ChatAzureOpenAI': ('agentyc.llm.azure.chat', 'ChatAzureOpenAI'),
+	'ChatOCIRaw': ('agentyc.llm.oci_raw.chat', 'ChatOCIRaw'),
+	'ChatOllama': ('agentyc.llm.ollama.chat', 'ChatOllama'),
+	'ChatVercel': ('agentyc.llm.vercel.chat', 'ChatVercel'),
+	'AgentycServer': ('agentyc.mcp.server', 'AgentycServer'),
+	'models': ('agentyc.llm.models', None),
+}
+
+
+def __getattr__(name: str):
+	"""Lazy import mechanism - only import modules when they're actually accessed."""
+	if name in _LAZY_IMPORTS:
+		module_path, attr_name = _LAZY_IMPORTS[name]
+		try:
+			from importlib import import_module
+
+			module = import_module(module_path)
+			attr = module if attr_name is None else getattr(module, attr_name)
+			globals()[name] = attr
+			return attr
+		except ImportError as e:
+			raise ImportError(f'Failed to import {name} from {module_path}: {e}') from e
+
+	raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = [
+	'ActionModel',
+	'ActionResult',
+	'BrowserSession',
+	'Browser',
+	'BrowserProfile',
+	'Controller',
+	'DomService',
+	'AgentycServer',
+	'ChatOpenAI',
+	'ChatGoogle',
+	'ChatAnthropic',
+	'ChatAgentyc',
+	'ChatGitHubCopilot',
+	'ChatGroq',
+	'ChatLiteLLM',
+	'ChatMistral',
+	'ChatAzureOpenAI',
+	'ChatOCIRaw',
+	'ChatOllama',
+	'ChatVercel',
+	'Tools',
+	'models',
+]