cellenium 0.1.0__py3-none-any.whl

cellenium/ai/agents/vision/config/agents.yaml

@@ -0,0 +1,10 @@
+vision:
+  role: >
+    Visual Evidence Analyst
+  goal: >
+    Extract precise, structured observations from supplied images without
+    inventing details that are not visibly supported.
+  backstory: >
+    You are a meticulous visual analyst. You distinguish direct observations
+    from uncertain interpretations, transcribe visible text exactly, and lower
+    confidence whenever image quality or ambiguity limits a finding.

cellenium/ai/agents/vision/config/tasks.yaml

@@ -0,0 +1,15 @@
+vision_task:
+  description: >
+    Analyze every image {image} attached to this crew run with prompt: {prompt}. 
+    Identify visible objects,
+    prominent colors, names or named entities, and dates. Report only evidence
+    supported by the image. Preserve visible spelling and date formatting,
+    omit duplicates, and use an empty list when a category has no findings.
+    Assign an overall confidence percentage that reflects image quality and
+    ambiguity.
+  expected_output: >
+    A VisionSchema-compatible object containing confidence_level (0 through
+    100), items_found (strings), colors (objects with name and an optional
+    six-digit RGB hex_code), names (strings), and dates (strings). Do not
+    include prose or fields outside the schema.
+  agent: vision

cellenium/ai/agents/vision/crew.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+from cellenium.ai.config import AgentConfig
+from crewai import Agent, Crew, Task
+from cellenium.ai.agents.vision.schemas import VisionSchema
+from cellenium.ai.agents.vision.tools.vision import VisionTool
+from crewai.project import CrewBase, agent, crew, task
+
+
+SKILLS = Path(__file__).resolve().parent / "skills"
+
+
+@CrewBase
+class Vision(AgentConfig):
+
+    @agent
+    def vision(self) -> Agent:
+        return Agent(config=self.agents_config["vision"], llm=self.llm, skills=[SKILLS])
+
+    @task
+    def vision_task(self) -> Task:
+        return Task(config=self.tasks_config["vision_task"], output_pydantic=VisionSchema, tools=[VisionTool(llm=self.llm)])
+
+    @crew
+    def crew(self) -> Crew:
+        return Crew(agents=self.agents, tasks=self.tasks, verbose=True)
+
+
+def run_vision_agent(image: list[str], prompt: str) -> VisionSchema:
+    return Vision().crew().kickoff({'image': image, 'prompt': prompt}).pydantic.model_dump()
+
+
+if __name__ == '__main__':
+    print(run_vision_agent(prompt='what is displayed?', image=[r'C:\Users\medvi\PycharmProjects\PythonProject\tests\files\images\img.png']))

cellenium/ai/agents/vision/schemas.py

@@ -0,0 +1,41 @@
+from typing import Annotated
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+
+VisionText = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=200)]
+
+
+class ColorFinding(BaseModel):
+    """A visible color and its optional six-digit RGB value."""
+    model_config = ConfigDict(extra="forbid", strict=True)
+    name: VisionText = Field(description="Common name of the visible color.")
+
+
+class VisionSchema(BaseModel):
+    """Structured, evidence-grounded observations from image analysis."""
+    model_config = ConfigDict(extra="forbid", strict=True)
+    confidence_level: float = Field(
+        ge=0,
+        le=100,
+        description="Overall confidence in the extracted findings, from 0 to 100.",
+    )
+    items_found: list[VisionText] = Field(
+        default_factory=list,
+        max_length=100,
+        description="Distinct visible objects or items, using short noun phrases.",
+    )
+    colors: list[ColorFinding] = Field(
+        default_factory=list,
+        max_length=50,
+        description="Colors visibly present in the image.",
+    )
+    names: list[VisionText] = Field(
+        default_factory=list,
+        max_length=100,
+        description="Names or named entities transcribed exactly as visible.",
+    )
+    dates: list[VisionText] = Field(
+        default_factory=list,
+        max_length=100,
+        description="Dates transcribed exactly as visible, without guessing a format.",
+    )

cellenium/ai/agents/vision/skills/evaluator/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: evaluator
+description: Verify proposed vision findings against image evidence before returning them.
+---
+
+## Evaluation Rules
+
+1. Re-check every proposed item, color, name, and date against the image.
+2. Remove findings that depend on assumptions, outside knowledge, or unreadable text.
+3. Keep exact transcriptions even when spelling or date formatting is unusual.
+4. Prefer omission over a plausible but unsupported guess.
+5. Confirm the confidence score reflects the least reliable material finding.
+6. Return only fields defined by the requested structured output schema.
+

cellenium/ai/agents/vision/skills/vision/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: vision
+description: Extract grounded objects, colors, visible names, and dates from attached images.
+---
+
+## Workflow
+
+1. Inspect each attached image before recording findings.
+2. Record only details directly supported by visible pixels.
+3. Use short noun phrases for objects and common names for colors.
+4. Transcribe names and dates exactly; do not normalize uncertain text.
+5. Remove duplicate findings across images.
+6. Use empty lists for categories with no visible evidence.
+
+## Confidence
+
+Set `confidence_level` from 0 to 100 for the result as a whole. Reduce it for
+blur, occlusion, low resolution, conflicting evidence, or uncertain text. Never
+raise confidence merely to make the output appear complete.

cellenium/ai/agents/vision/tools/vision.py

@@ -0,0 +1,167 @@
+import io
+import base64
+from pathlib import Path
+from typing import Optional, Union, Type, List, Any
+from dataclasses import dataclass
+from PIL import Image
+from crewai import LLM
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field, field_validator
+
+
+# log = Logger(name="vision-tool")
+
+MAX_IMAGE_RESOLUTION = 2048
+
+LLMMessage = dict[str, Any]
+
+
+# ------------------------------ #
+#        Utility Functions       #
+# ------------------------------ #
+
+def is_base64(value: str) -> bool:
+    """Return True if value is raw base64 or a data URI, not a file path."""
+    return value.startswith("data:image/") or not Path(value).exists()
+
+
+def resolve_path(path: str) -> str:
+    """Resolve and validate file path."""
+    resolved = Path(path).resolve()
+    if not resolved.exists():
+        # log.fire(f"Image file does not exist: {resolved}", level='debug')
+        raise ValueError(f"Image file not found: {resolved}")
+    return str(resolved)
+
+
+def normalize_paths(value: Optional[Union[str, List[str]]]) -> Optional[List[str]]:
+    """Normalize optional image paths/base64 values to list."""
+    if value is None:
+        return None
+    paths = [value] if isinstance(value, str) else value
+    for p in paths:
+        if not is_base64(p):
+            resolve_path(p)
+    return paths
+
+
+def _pil_to_jpeg_b64(img: "Image.Image") -> str:
+    if img.mode in ("RGBA", "LA", "P"):
+        img = img.convert("RGB")
+    if max(img.size) > MAX_IMAGE_RESOLUTION:
+        img.thumbnail((MAX_IMAGE_RESOLUTION, MAX_IMAGE_RESOLUTION), Image.LANCZOS)
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG", quality=95, subsampling=0)
+    return f"data:image/jpeg;base64,{base64.b64encode(buf.getvalue()).decode()}"
+
+
+def encode_image(path_or_b64: str) -> str:
+    """Encode image as base64 data URI. Accepts a file path, raw base64, or data URI."""
+    if path_or_b64.startswith("data:image/"):
+        raw = base64.b64decode(path_or_b64.split(",", 1)[1])
+    elif is_base64(path_or_b64):
+        raw = base64.b64decode(path_or_b64)
+    else:
+        try:
+            img = Image.open(resolve_path(path_or_b64))
+            return _pil_to_jpeg_b64(img)
+        except Exception as e:
+            raise ValueError(f"Cannot open image '{path_or_b64}': {e}") from e
+
+    try:
+        img = Image.open(io.BytesIO(raw))
+        return _pil_to_jpeg_b64(img)
+    except Exception as e:
+        raise ValueError(f"Failed to process image data: {e}") from e
+
+
+# ------------------------------ #
+#         Pydantic Schema        #
+# ------------------------------ #
+
+class ImagePromptSchema(BaseModel):
+
+    image_path:   str                             = Field(...,          description="Primary image path")
+    sample_image: Optional[Union[str, List[str]]] = Field(default=None, description="Optional comparison image path(s)")
+    prompt:       str                             = Field(...,          description="Prompt describing what to analyze in the image")
+
+    @classmethod
+    @field_validator("image_path")
+    def validate_image(cls, v: str) -> str:
+        return v if is_base64(v) else resolve_path(v)
+
+    @classmethod
+    @field_validator("sample_image")
+    def validate_sample_images(cls, v):
+        return normalize_paths(v)
+
+    def get_all_images(self) -> List[str]:
+        """Return all image paths used in the request."""
+        images = [self.image_path]
+
+        if self.sample_image:
+            images.extend(self.sample_image)
+
+        # log.fire(f"Vision images used: {images}", level='debug')
+
+        return images
+
+
+# ------------------------------ #
+#          Tool Runtime          #
+# ------------------------------ #
+
+@dataclass
+class VisionMessageBuilder:
+
+    schema: ImagePromptSchema
+
+    def build(self) -> List[LLMMessage]:
+        images = [
+            {
+                "type": "image_url",
+                "image_url": {"url": encode_image(path)},
+            }
+            for path in self.schema.get_all_images()
+        ]
+
+        return [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": self.schema.prompt},
+                    *images
+                ],
+            }
+        ]
+
+
+# ------------------------------ #
+#        Vision Tool Class       #
+# ------------------------------ #
+
+class VisionTool(BaseTool):
+
+    name:        str             = "Bini Vision Tool"
+    description: str             = "Analyzes one or more images using a vision-capable LLM"
+    args_schema: Type[BaseModel] = ImagePromptSchema
+
+    def __init__(self, llm: LLM) -> None:
+
+        super().__init__()
+
+        if llm is None:
+            raise ValueError("BiniVisionTool requires a valid LLM instance")
+
+        self._llm = llm
+
+    @staticmethod
+    def _build_messages(schema: ImagePromptSchema) -> List[LLMMessage]:
+        """Construct messages for the vision model."""
+        builder = VisionMessageBuilder(schema=schema)
+        return builder.build()
+
+    def _run(self, **kwargs: Any) -> str:
+        schema = ImagePromptSchema(**kwargs)
+        messages = self._build_messages(schema)
+        return self._llm.call(messages=messages)

cellenium/ai/config.py

@@ -0,0 +1,17 @@
+from asyncio import Task
+from crewai import LLM
+from cellenium.settings import get_config
+from functools import cached_property
+from crewai.agents.agent_builder.base_agent import BaseAgent
+
+
+class AgentConfig:
+
+    agents: list[BaseAgent]
+    tasks: list[Task]
+    agents_config: dict = 'config/agents.yaml'
+    tasks_config: dict = 'config/tasks.yaml'
+
+    @cached_property
+    def llm(self) -> LLM:
+        return LLM(model=get_config().OPENAI_MODEL)

cellenium/ai/tools/image_encoder.py

@@ -0,0 +1,10 @@
+import base64
+import mimetypes
+from pathlib import Path
+
+
+def encode_image_to_data_uri(image_path: str) -> str:
+    path = Path(image_path)
+    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
+    encoded = base64.b64encode(path.read_bytes()).decode("utf-8")
+    return f"data:{mime_type};base64,{encoded}"

cellenium/engine/manager.py

@@ -0,0 +1,48 @@
+"""
+Bootstrap a Playwright browser/context/page.
+
+Playwright ships and manages its own browser binaries (one-time setup:
+`playwright install chromium`) - unlike Selenium, there is no driver-manager
+download step to wire up here.
+"""
+from typing import Optional
+from dataclasses import dataclass, field
+from playwright.sync_api import sync_playwright, Browser, BrowserContext, Page, Playwright
+from cellenium.settings import get_config
+
+
+@dataclass
+class BrowserManager:
+
+    """
+    Launches a Playwright browser, context, and page for the lifetime of the instance.
+
+    :param headless: run without a visible UI window.
+    :param browser_name: one of "chromium", "firefox", "webkit".
+    :param http_credentials: optional {"username": ..., "password": ...} for HTTP basic
+        auth - Playwright only accepts this at context-creation time, so it is a
+        constructor field here rather than a runtime method.
+    """
+
+    headless: Optional[bool] = None
+    browser_name: str = "chromium"
+    http_credentials: Optional[dict] = None
+    playwright: Playwright = field(init=False, repr=False)
+    browser: Browser = field(init=False, repr=False)
+    context: BrowserContext = field(init=False, repr=False)
+    page: Page = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.headless is None:
+            self.headless = get_config().TEST_HEADLESS
+        self.playwright = sync_playwright().start()
+        launcher = getattr(self.playwright, self.browser_name)
+        self.browser = launcher.launch(headless=self.headless)
+        self.context = self.browser.new_context(http_credentials=self.http_credentials)
+        self.page = self.context.new_page()
+
+    def teardown(self) -> None:
+        self.page.close()
+        self.context.close()
+        self.browser.close()
+        self.playwright.stop()

cellenium/engine/page_engine.py

@@ -0,0 +1,79 @@
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional
+from playwright.sync_api import Locator
+from cellenium.engine.manager import BrowserManager
+from cellenium.functions.locators import get_entry, get_locator
+from cellenium.functions.logger import Logger
+
+
+SCREENSHOTS = Path("data") / "screenshots"  # relative to the working directory, not the installed package
+
+log = Logger(name='browser-manager')
+
+
+@dataclass
+class PageEngine(BrowserManager):
+
+    screen: Optional[str] = None
+
+    def get_web(self, url: str) -> None:
+        self.page.goto(url)
+        log.fire(message=f'web opened: {url} using: {self.screen} screen')
+
+    def get_element(self, name: str, timeout: int = 10_000) -> Locator:
+        locator = get_locator(self.page, self.screen, name)
+        locator.wait_for(state="attached", timeout=timeout)
+        log.fire(message=f'element used: {name}')
+        return locator
+
+    def get_dynamic_element(self, attribute: str, name: str) -> Locator:
+        # explanation ............ //*[contains(@<attribute>, <name>)]
+        # example ................ //*[contains(@name, "btnK")]
+        entry = get_entry(self.screen, name)
+        path = f"//*[contains(@{attribute}, '{entry['value']}')]"
+        return self.page.locator(f"xpath={path}")
+
+    def wait_for_element(self, name: str, timeout: int = 5_000) -> Locator:
+        locator = get_locator(self.page, self.screen, name)
+        locator.wait_for(state="visible", timeout=timeout)
+        log.fire(message=f'waiting for element: {name}')
+        return locator
+
+    def get_screenshot(self, name: Optional[str] = None) -> str:
+        SCREENSHOTS.mkdir(parents=True, exist_ok=True)
+        file_name = f"{name or uuid.uuid4()}.png"
+        path = SCREENSHOTS / file_name
+        self.page.screenshot(path=str(path))
+        return str(path)
+
+    def dropdown(self, name: str, label: str) -> None:
+        self.get_element(name).select_option(label=label)
+
+    def count_elements(self, name: str, tag: str) -> int:
+        count = self.get_element(name).locator(tag).count()
+        print(f"number of rows in this page is: {count}")
+        return count
+
+    def count_rows(self, name: str, structure: str) -> int:
+        return self.get_element(name).locator(structure).count()
+
+    def press_keyboard_key(self, key: str) -> None:
+        self.page.keyboard.press(f"Control+{key}")
+
+    def scroll_page(self, direction: Literal['up', 'down'], px: int) -> None:
+        match direction:
+            case "up":
+                self.page.mouse.wheel(0, -px)
+            case "down":
+                self.page.mouse.wheel(0, px)
+
+    def switch_to_new_tab(self, url: str) -> None:
+        new_page = self.context.new_page()
+        new_page.goto(url)
+        log.fire(message=f'url switched to {url}')
+
+    def switch_to_main_tab(self) -> None:
+        self.page = self.context.pages[0]
+        self.page.bring_to_front()

cellenium/functions/locators.py

@@ -0,0 +1,38 @@
+from collections.abc import Callable
+
+from playwright.sync_api import Locator, Page
+
+from cellenium.functions.sheets import fetch_locators
+
+# Selenium's find_element silently returns the first match; Playwright locators are
+# strict-mode by default and raise on multiple matches, so each strategy here resolves
+# to the first match (via .first) to keep that same "resolve to one element" semantics.
+LOCATOR_MAP: dict[str, Callable[[Page, str], Locator]] = {
+    "NAME": lambda page, v: page.locator(f'[name="{v}"]').first,
+    "XPATH": lambda page, v: page.locator(f"xpath={v}").first,
+    "ID": lambda page, v: page.locator(f"#{v}").first,
+    "CSS": lambda page, v: page.locator(v).first,
+    "CLASS_NAME": lambda page, v: page.locator(f".{v}").first,
+    "LINK_TEXT": lambda page, v: page.get_by_text(v, exact=True).first,
+    "TAG_NAME": lambda page, v: page.locator(v).first,
+}
+
+
+def get_entry(screen: str | None, name: str) -> dict[str, str]:
+    """Look up a raw POM entry from the worksheet selected by screen."""
+    entries = fetch_locators(screen)
+    if name not in entries:
+        raise KeyError(f"No locator named {name!r} on screen {screen!r}")
+
+    return entries[name]
+
+
+def get_locator(page: Page, screen: str | None, name: str) -> Locator:
+    """Resolve a Google Sheets POM entry to a Playwright Locator."""
+    entry = get_entry(screen, name)
+    strategy = entry["type"]
+    try:
+        builder = LOCATOR_MAP[strategy]
+    except KeyError:
+        raise ValueError(f"Unsupported locator strategy {strategy!r} for {name!r} on screen {screen!r}")
+    return builder(page, entry["value"])

cellenium/functions/logger.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass
+from functools import cached_property
+from typing import Literal
+
+import logfire
+
+from cellenium.settings import get_config
+
+LogLevel = Literal["info", "error", "debug", "warning", "fatal"]
+
+
+@dataclass
+class Logger:
+
+    name: str
+
+    @cached_property
+    def config(self):
+        # Configured on first log call so module-level loggers don't load settings at import time.
+        return logfire.configure(
+            token=get_config().LOGFIRE_TOKEN,
+            send_to_logfire="if-token-present",
+        )
+
+    def fire(self, message: str, level: LogLevel | None = 'info', **attributes: object) -> None:
+        with self.config.span(self.name):
+            match level:
+                case "info":
+                    self.config.info(message, **attributes)
+                case "error":
+                    self.config.error(message, **attributes)
+                case "debug":
+                    self.config.debug(message, **attributes)
+                case "warning":
+                    self.config.warning(message, **attributes)
+                case "fatal":
+                    self.config.fatal(message, **attributes)
+                case _:
+                    self.config.info(message, **attributes)
+
+
+if __name__ == "__main__":
+    logger = Logger(name="app")
+    logger.fire(message="hi")

cellenium/functions/sheets.py

@@ -0,0 +1,71 @@
+"""
+Read Page Object Model locators directly from Google Sheets.
+Uses gspread with a service-account credentials.json (no "anyone with the
+link" sharing required) - the sheet just needs to be shared with the service
+account's client_email (see credentials.json) as a Viewer.
+
+Each worksheet (tab) in the spreadsheet is one screen. Callers select the
+worksheet by passing the same screen name used by ``PageEngine``.
+
+Sheet columns (per the QA team's POM sheet):
+    name    - identifier used to look up the locator in code
+    locator - the strategy, e.g. NAME / XPATH / ID / CSS
+    type    - the actual locator value (confusingly named, but matches the sheet)
+    actions - optional
+    comments - optional
+"""
+
+import gspread
+from pathlib import Path
+from typing import Optional
+from cellenium.functions.logger import Logger
+from cellenium.settings import get_config
+
+
+log = Logger('sheets-logic')
+
+
+def _parse_worksheet(worksheet: gspread.Worksheet) -> dict[str, dict[str, str]]:
+
+    rows = worksheet.get_all_values()
+
+    if not rows:
+        log.fire(message='no rows were found', level='debug')
+        return {}
+
+    header = [h.strip().lower() for h in rows[0]]
+    locators: dict[str, dict[str, str]] = {}
+
+    for row in rows[1:]:
+        record = dict(zip(header, row))
+        name = record.get("name", "").strip()
+        if not name:
+            continue
+        locators[name] = {
+            "type": record.get("locator", "").strip().upper(),
+            "value": record.get("type", "").strip(),
+            "actions": record.get("actions", "").strip(),
+            "comments": record.get("comments", "").strip(),
+        }
+    return locators
+
+
+def fetch_locators(screen: Optional[str] = None, credentials_path: Optional[Path] = None) -> dict[str, dict]:
+    """Read all locator rows from one worksheet selected by screen name."""
+    if not screen:
+        message = 'screen is required to select a Google Sheets worksheet'
+        log.fire(message=message, level='error')
+        raise ValueError(message)
+
+    config = get_config()
+    gc = gspread.service_account(filename=str(credentials_path or config.CREDENTIALS_JSON))
+    spreadsheet = gc.open_by_url(config.GOOGLE_SHEETS)
+
+    try:
+        worksheet = spreadsheet.worksheet(screen)
+
+    except gspread.WorksheetNotFound as e:
+        log.fire(f"No worksheet named {screen!r} in the configured Google Sheet", level='error')
+        raise ValueError from e
+
+    return _parse_worksheet(worksheet)

cellenium/settings.py

@@ -0,0 +1,26 @@
+from functools import cache
+from pathlib import Path
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+
+    # Relative paths resolve against the current working directory, i.e. the project using cellenium.
+    model_config = SettingsConfigDict(env_file=".env", extra="allow")
+
+    GOOGLE_SHEETS:        str         = Field(...,                       description='')
+    GOOGLE_SHEET_API_KEY: str         = Field(...,                       description='')
+    GOOGLE_SHEET_EMAIL:   str         = Field(...,                       description='')
+    GOOGLE_SHEET_ID:      str         = Field(...,                       description='')
+    OPENAI_MODEL:         str         = Field(...,                       description='')
+    OPENAI_API_KEY:       str | None  = Field(None,                      description='')
+    LOGFIRE_TOKEN:        str | None  = Field(None,                      description='')
+    TEST_HEADLESS:        bool        = Field(True,                      description='')
+    CREDENTIALS_JSON:     Path        = Field(Path("credentials.json"), description='google json credentials for accessing the sheet')
+
+
+@cache
+def get_config() -> Settings:
+    """Load settings on first use so importing cellenium never requires a configured environment."""
+    return Settings()

cellenium-0.1.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: cellenium
+Version: 0.1.0
+Summary: Playwright browser automation with a Google Sheets Page Object Model and CrewAI vision analysis
+Project-URL: Homepage, https://github.com/MedviJenka/cellenium-playwright
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: crewai>=1.15.23
+Requires-Dist: fastapi>=0.142.2
+Requires-Dist: gspread>=6.2.1
+Requires-Dist: importlib-metadata>=8.0.0
+Requires-Dist: logfire>=3.5.1
+Requires-Dist: oauth2client>=4.1.3
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: playwright>=1.63.0
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: uvicorn>=0.54.0
+Description-Content-Type: text/markdown
+
+# Cellenium Playwright
+
+Cellenium Playwright is an experimental Python browser-automation toolkit built on [Playwright](https://playwright.dev/python/). It provides browser lifecycle management, a Google-Sheets-backed Page Object Model (POM), screenshot capture, and components for structured visual analysis with CrewAI.
+
+The repository also contains **TestFlow**, a set of Claude Code skills that turns product requirements and technical specifications into traceable pytest tests, validated UI locators, execution evidence, and a test-quality verdict.
+
+> **Status:** active development. The browser and locator layers are usable, but the checked-in vision test is still a scaffold and does not currently pass. Install it from PyPI with `pip install cellenium` (or `uv add cellenium`), then run `playwright install chromium`. Configuration (`.env`, `credentials.json`) is read from your project's working directory.
+
+## Features
+
+- Synchronous Chromium, Firefox, or WebKit sessions through Playwright.
+- Reusable `PageEngine` helpers for navigation, locators, screenshots, scrolling, dropdowns, and tabs.
+- Page Object Model data read directly from Google Sheets at runtime.
+- Locator strategies for name, XPath, ID, CSS, class name, link text, and tag name.
+- Structured image-analysis components built with CrewAI and Pydantic.
+- Parallel pytest execution in CI on Python 3.13 and 3.14.
+- Optional TestFlow skills for end-to-end pytest test generation and evaluation.
+
+## Requirements
+
+- Python 3.13 or 3.14
+- [`uv`](https://docs.astral.sh/uv/)
+- A Playwright-supported browser
+- A Google service account for resolving locators
+- An OpenAI-compatible model and API key when using the vision components
+
+## Quick start
+
+Clone the repository and install the locked dependencies:
+
+```sh
+git clone https://github.com/MedviJenka/cellenium-playwright.git
+cd cellenium-playwright
+uv sync --frozen
+```
+
+Install Chromium:
+
+```sh
+uv run playwright install chromium
+```
+
+On Ubuntu or another Debian-based CI runner, install Chromium and its system dependencies together:
+
+```sh
+uv run playwright install --with-deps chromium
+```
+
+## Configuration
+
+Create `.env` in the repository root. Optional values are labeled below:
+
+```dotenv
+GOOGLE_SHEETS=<spreadsheet-id-or-edit-url>
+GOOGLE_SHEET_API_KEY=<google-api-key>
+GOOGLE_SHEET_EMAIL=<service-account-email>
+GOOGLE_SHEET_ID=<spreadsheet-id>
+OPENAI_MODEL=<model-name>
+OPENAI_API_KEY=<optional-api-key>
+LOGFIRE_TOKEN=<optional-logfire-token>
+TEST_HEADLESS=true
+```
+
+`GOOGLE_SHEETS` selects the locator spreadsheet. When `LOGFIRE_TOKEN` is omitted, logging remains local and no data is sent to Logfire.
+
+Place the Google service-account document at:
+
+```text
+credentials.json
+```
+
+Share the locator spreadsheet with the service account's `client_email` as a viewer. Never commit `.env` or `credentials.json`; both are ignored by Git.
+
+## Google Sheets Page Object Model
+
+Each worksheet tab represents one screen. The first row must contain these columns:
+
+| Column | Purpose |
+|---|---|
+| `name` | Logical element name used by tests |
+| `locator` | Locator strategy such as `NAME`, `XPATH`, `ID`, or `CSS` |
+| `type` | Locator value; this name is retained for compatibility with the source sheet |
+| `actions` | Optional metadata |
+| `comments` | Optional notes |
+
+Example worksheet:
+
+| name | locator | type | actions | comments |
+|---|---|---|---|---|
+| search | NAME | q | fill | Google search field |
+| button | NAME | btnK | click | Search button |
+
+`PageEngine(screen="Google")` reads locator rows directly from the worksheet tab
+named `Google`. No generated JSON mapping or synchronization step is required.
+
+## Browser automation
+
+```python
+from src.core.engine.page_engine import PageEngine
+
+engine = PageEngine(screen="Google", headless=True)
+
+try:
+    engine.get_web("https://www.google.com")
+    engine.get_element("search").fill("cats")
+    engine.get_element("button").click()
+    screenshot = engine.get_screenshot("google-results")
+    print(screenshot)
+finally:
+    engine.teardown()
+```
+
+`screen="Google"` selects the worksheet tab named `Google`. With multiple tabs, pass the page's tab name when constructing `PageEngine` (for example, `Google`, `Heroku`, or `ST`). Missing worksheets, missing element names, and unsupported locator strategies raise explicit exceptions.
+
+## Tests and linting
+
+Run the test suite:
+
+```sh
+uv run --frozen pytest src/tests tests -v -n auto --dist loadscope
+```
+
+`src/tests/test_google_search.py` exercises the live browser flow. The unit regressions in `tests/` cover screenshot persistence and direct worksheet selection without contacting external services.
+
+Run the blocking CI lint checks:
+
+```sh
+uvx --from flake8==7.4.1 flake8 main.py settings.py src \
+  --count --select=E9,F63,F7,F82 --show-source --statistics
+```
+
+The GitHub Actions workflow in `.github/workflows/python-package.yml` performs locked dependency installation, installs Chromium, runs lint checks, and executes the tests under Xvfb for Python 3.13 and 3.14.
+
+## TestFlow Claude Code skills
+
+TestFlow separates pytest creation into focused stages:
+
+```text
+PRD → test specification → UI locators → pytest writer → executor → evaluator
+```
+
+| Order | Skill | Purpose |
+|---:|---|---|
+| Optional | `web` | Explore a live application in a real browser and produce reproducible bug evidence |
+| 1 | `prd-reader` | Extract explicit, derived, and unknown test requirements from the PRD |
+| 2 | `test-spec` | Design traceable pytest cases, boundaries, fixtures, and execution prerequisites |
+| 3 | `locator-writer` | For UI cases, validate stable Playwright selectors and upsert elements into Google Sheets |
+| 4 | `writer` | Implement deterministic, behavior-focused pytest tests |
+| 5 | `executor` | Run collection, targeted tests, related tests, and classify failures |
+| 6 | `evaluator` | Evaluate traceability, regression sensitivity, coverage quality, and execution evidence |
+
+`artifact` orchestrates the complete pipeline and repeats only the affected downstream stages when evaluation finds a defect.
+
+`web` is a report-only exploratory entry point. Verified findings become regression candidates for `test-spec`; it does not modify application code.
+
+Validate the Claude Code plugin metadata:
+
+```sh
+claude plugin validate .
+```
+
+Run Claude Code from the repository and invoke either the complete pipeline or an individual stage:
+
+```text
+/testflow:web
+/testflow:artifact
+/testflow:prd-reader
+/testflow:test-spec
+/testflow:locator-writer
+/testflow:writer
+/testflow:executor
+/testflow:evaluator
+```
+
+The skills are manual-only. The locator writer previews changes before replacing existing Google Sheet selectors and verifies selectors against the live UI.
+
+The separate checklist skills live under `.claude/skills/checklist/`: `before-startup` (system ready to build tests), `cruising` (everything in place, critical errors and potential bugs), `landing` (final production readiness), and the standalone `fordec` emergency decision skill.
+
+## Project layout
+
+```text
+.github/workflows/               GitHub Actions CI
+.claude/skills/testflow/         Pytest TestFlow skill definitions
+.claude/skills/checklist/        Checklist skills (before-startup, cruising, landing, fordec)
+.claude/commands/testflow/       TestFlow slash-command entries
+.claude-plugin/plugin.json       Claude Code plugin metadata
+src/core/engine/                 Playwright browser and page engines
+src/core/functions/              Locator resolution and direct Google Sheets access
+src/core/ai/                     CrewAI configuration and vision components
+src/tests/                       Browser test scenarios
+settings.py                      Environment-backed runtime configuration
+pyproject.toml                   Python requirements and dependencies
+uv.lock                          Reproducible dependency lockfile
+```
+
+## Known limitations
+
+- The checked-in vision test uses a placeholder `VisionAssertion` without a `run()` implementation.
+- The sample end-to-end test depends on Google and is not hermetic.
+- Configuration currently requires fields that are reserved but not consumed by every component.
+- The project does not yet define a wheel/sdist build or publishing workflow.
+
+## License
+
+Licensed under the [ISC License](LICENSE). Copyright © 2026 Jenia Petrusenko.

cellenium-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+cellenium/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/settings.py,sha256=6r5flnKTZ0Sr16Y_SIuPXQEGr-bWtR9N6UirColrEiQ,1384
+cellenium/ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/ai/config.py,sha256=xpT5HDa0A1ff_H-UyZAVWHb_t2WhLJG9Ysx5NVpTTbk,470
+cellenium/ai/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/ai/agents/vision/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/ai/agents/vision/crew.py,sha256=-LKXwVYVQjCrnhbfVoTx39l1P6oDcAPhLsA2Xb0d6Ps,1158
+cellenium/ai/agents/vision/schemas.py,sha256=KZPZYlPzC95GPyEfz-qNYpC-HMLs8E0INIoKzf70ixY,1505
+cellenium/ai/agents/vision/config/agents.yaml,sha256=ukcIjykZ8_M8NDQwsByUgU2L7UPdHK23x3c2YhzGMLU,434
+cellenium/ai/agents/vision/config/tasks.yaml,sha256=oV4aA1WxgjEzeOwvI73mqCM5XmlV_stZ9Li5vi2S2S8,788
+cellenium/ai/agents/vision/skills/evaluator/SKILL.md,sha256=icUO8l-eum2qAkb7hXnRJ817BDedv3WMXMHRPMpvgVs,601
+cellenium/ai/agents/vision/skills/vision/SKILL.md,sha256=m75iOqKpqAguUolohZ9cKnifzqElej6NVdyvgvYLl2M,744
+cellenium/ai/agents/vision/tools/vision.py,sha256=fx9Pfwh-VmItyAcdiAum_9ROWH8mlDwgJ9WT68qd9xg,5319
+cellenium/ai/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/ai/tools/image_encoder.py,sha256=b4M5W_FwJ2iH8ZwS4AmCBbXXpZ-fM6YlYkapzHDLUoY,330
+cellenium/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/engine/manager.py,sha256=Fi7lTVXtkI8Lht-tAJuYr1gfraEEBo2ExmgIpfi2-fg,1892
+cellenium/engine/page_engine.py,sha256=iwaDj9R5IjZym86nz9uh9yONqAj8h2WIocQ2gQVXrM0,3032
+cellenium/functions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellenium/functions/locators.py,sha256=hoCfO8zg9dljeK1squKyt-sH5dKjZaRC0jtKZcivkBs,1648
+cellenium/functions/logger.py,sha256=68uZtamrCtCqmHMSwcXcDUPiz4HkjhXz0rbEYanFzU0,1344
+cellenium/functions/sheets.py,sha256=UYQUmZYrTOZlWN1oapzLwOnQ1ZxQAHiTu24ggCF1UL0,2545
+cellenium-0.1.0.dist-info/METADATA,sha256=NN_aezscdzaya0FhxMjWVRKJ9dISAXHF7jeM4bdtaKk,8990
+cellenium-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+cellenium-0.1.0.dist-info/licenses/LICENSE,sha256=TsSLLu43bQqPdjqazLS4p4OpWvYomR6MYlLs10is-P4,754
+cellenium-0.1.0.dist-info/RECORD,,

cellenium-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

cellenium-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 Jenia Petrusenko
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.