{"owner":"ValueCell-ai","repo":"valuecell","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Guidelines\n\n## Python Programming\n\n### Python Environment\n\n* Package manager: uv\n* Virtual environment: `./python/.venv`\n* Testing command: `uv run pytest`\n\n### Imports\n\n* Avoid inline imports unless required to break a circular dependency.\n* If you import more than three names from a single module, prefer qualified imports:\n  * Prefer: `import pathlib; pathlib.Path, pathlib.PurePath`\n  * Avoid: `from pathlib import Path, PurePath, PurePosixPath, ...`\n* Postpone changes to `__init__` and `__all__` until APIs stabilize.\n* Use TYPE_CHECKING for imports only needed for type hints.\n\n```python\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from mypkg.schemas import AgentConfig\n```\n\n### Runtime Checks\n\n* Avoid excessive use of `getattr`, `hasattr`, and runtime type checks.\n* If an object is a pydantic `BaseModel`, prefer using its validated attributes and type annotations instead of probing attributes at runtime.\n* Rely on pydantic validation, model validators, and type hints; prefer `TypedDict` or `Protocol` for structural typing when appropriate.\n* When runtime checks are necessary, make them explicit, minimal, and well-documented so the reason for the guard is clear.\n\n### Async-First Design\n\n* Prefer asynchronous APIs for I/O-bound work.\n* Use asyncio or anyio; for HTTP, prefer httpx (async client).\n* Ensure clear async boundaries: public APIs and I/O paths should be async.\n* Provide minimal sync adapters only when needed, and document them.\n\n```python\nimport asyncio\nfrom loguru import logger\nimport httpx\n\nasync def fetch_agent_state(url: str, timeout_s: float) -> dict:\n    \"\"\"Fetch agent state from a remote endpoint.\"\"\"\n    async with httpx.AsyncClient(timeout=timeout_s) as client:\n        resp = await client.get(url)\n        resp.raise_for_status()\n        data = resp.json()\n        logger.info(\"Fetched state from {url}\", url=url)\n        return data\n\ndef fetch_agent_state_sync(url: str, timeout_s: float) -> dict:\n    \"\"\"Synchronous adapter. Prefer the async variant.\"\"\"\n    return asyncio.run(fetch_agent_state(url, timeout_s))\n```\n\n### Logging\n\n* Use loguru; placeholders must be {} rather than %.\n* Log key events at info; avoid excessive logging.\n* Do not log sensitive data.\n* Use `logger.exception` sparingly: only for truly unexpected errors that require stack traces for debugging. For expected or recoverable errors, prefer `logger.warning` or `logger.error` with explicit context.\n* Prefer `logger.warning` for recoverable issues, degraded states, or when an operation can continue despite an error.\n\n```python\nfrom loguru import logger\n\ndef process_items(items: list[str]) -> int:\n    \"\"\"Process items and return count.\"\"\"\n    count = len(items)\n    logger.info(\"Processing {count} items\", count=count)\n    # ...\n    logger.info(\"Processed {count} items\", count=count)\n    return count\n\n# Good: expected error, use warning with context\nasync def send_notification(msg: str) -> None:\n    \"\"\"Send notification; log warning if it fails (non-critical).\"\"\"\n    try:\n        await notify_service(msg)\n    except NetworkError as exc:\n        logger.warning(\"Notification failed, continuing: {err}\", err=str(exc))\n\n# Good: unexpected error requiring investigation, use exception\nasync def critical_operation() -> None:\n    \"\"\"Perform critical operation that should never fail.\"\"\"\n    try:\n        await process_critical_data()\n    except Exception:\n        logger.exception(\"Critical operation failed unexpectedly\")\n        raise\n```\n\n### Type Hints and Comments\n\n* Add type hints across public and internal APIs.\n* Comments and docstrings should be in English and explain why, not only what.\n* Use Protocols and TypedDict or pydantic models where appropriate.\n* Avoid excessive literal dict access (for example, using `obj['key']` everywhere); prefer typed structures such as `dataclass`, pydantic models, or `TypedDict` for clearer contracts and better type safety.\n\n### Error Handling\n\n* Keep try-except depth to at most two levels.\n* Catch specific exceptions. Re-raise with context if needed.\n* Prefer explicit None checks and guard clauses over broad exception use.\n\n```python\nimport json\nfrom loguru import logger\n\ndef parse_payload(raw: str) -> dict:\n    \"\"\"Parse payload; return empty dict on known format errors.\"\"\"\n    try:\n        data = json.loads(raw)\n    except json.JSONDecodeError as exc:\n        logger.info(\"Invalid JSON: {err}\", err=str(exc))\n        return {}\n    return data\n```\n\n### Structure and Size\n\n* Avoid nested functions; extract helpers at module level.\n* Keep functions under 200 lines. Split into well-named helpers.\n* Avoid functions with more than 10 parameters; prefer wrapping parameters in a struct or object.\n* Separate concerns: I/O, parsing, business logic, and orchestration.\n\n### Strings and Literals\n\n* Avoid long string literals; wrap lines under 100 characters.\n* Avoid magic numbers and ad-hoc string literals. Centralize constants.\n\n```python\n# constants.py\nDEFAULT_TIMEOUT_S: float = 10.0\nMAX_RETRIES: int = 3\n```\n\n### Boolean Logic\n\n* Be careful with or where 0, empty, or False may be meaningful.\n* Prefer explicit checks:\n\n```python\n# Prefer\nvalue = user_value if user_value is not None else default\n\n# Avoid\nvalue = user_value or default\n```\n\n### Module and Package Layout\n\n* Group agent core, adapters, and utilities into separate modules.\n* Keep public surface small. Delay re-exports in __init__ until stable.\n* If circular dependencies appear, refactor shared contracts to a thin shared module (e.g., interfaces.py or contracts.py).\n"},"files":{"AGENTS.md":"# Guidelines\n\n## Python Programming\n\n### Python Environment\n\n* Package manager: uv\n* Virtual environment: `./python/.venv`\n* Testing command: `uv run pytest`\n\n### Imports\n\n* Avoid inline imports unless required to break a circular dependency.\n* If you import more than three names from a single module, prefer qualified imports:\n  * Prefer: `import pathlib; pathlib.Path, pathlib.PurePath`\n  * Avoid: `from pathlib import Path, PurePath, PurePosixPath, ...`\n* Postpone changes to `__init__` and `__all__` until APIs stabilize.\n* Use TYPE_CHECKING for imports only needed for type hints.\n\n```python\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from mypkg.schemas import AgentConfig\n```\n\n### Runtime Checks\n\n* Avoid excessive use of `getattr`, `hasattr`, and runtime type checks.\n* If an object is a pydantic `BaseModel`, prefer using its validated attributes and type annotations instead of probing attributes at runtime.\n* Rely on pydantic validation, model validators, and type hints; prefer `TypedDict` or `Protocol` for structural typing when appropriate.\n* When runtime checks are necessary, make them explicit, minimal, and well-documented so the reason for the guard is clear.\n\n### Async-First Design\n\n* Prefer asynchronous APIs for I/O-bound work.\n* Use asyncio or anyio; for HTTP, prefer httpx (async client).\n* Ensure clear async boundaries: public APIs and I/O paths should be async.\n* Provide minimal sync adapters only when needed, and document them.\n\n```python\nimport asyncio\nfrom loguru import logger\nimport httpx\n\nasync def fetch_agent_state(url: str, timeout_s: float) -> dict:\n    \"\"\"Fetch agent state from a remote endpoint.\"\"\"\n    async with httpx.AsyncClient(timeout=timeout_s) as client:\n        resp = await client.get(url)\n        resp.raise_for_status()\n        data = resp.json()\n        logger.info(\"Fetched state from {url}\", url=url)\n        return data\n\ndef fetch_agent_state_sync(url: str, timeout_s: float) -> dict:\n    \"\"\"Synchronous adapter. Prefer the async variant.\"\"\"\n    return asyncio.run(fetch_agent_state(url, timeout_s))\n```\n\n### Logging\n\n* Use loguru; placeholders must be {} rather than %.\n* Log key events at info; avoid excessive logging.\n* Do not log sensitive data.\n* Use `logger.exception` sparingly: only for truly unexpected errors that require stack traces for debugging. For expected or recoverable errors, prefer `logger.warning` or `logger.error` with explicit context.\n* Prefer `logger.warning` for recoverable issues, degraded states, or when an operation can continue despite an error.\n\n```python\nfrom loguru import logger\n\ndef process_items(items: list[str]) -> int:\n    \"\"\"Process items and return count.\"\"\"\n    count = len(items)\n    logger.info(\"Processing {count} items\", count=count)\n    # ...\n    logger.info(\"Processed {count} items\", count=count)\n    return count\n\n# Good: expected error, use warning with context\nasync def send_notification(msg: str) -> None:\n    \"\"\"Send notification; log warning if it fails (non-critical).\"\"\"\n    try:\n        await notify_service(msg)\n    except NetworkError as exc:\n        logger.warning(\"Notification failed, continuing: {err}\", err=str(exc))\n\n# Good: unexpected error requiring investigation, use exception\nasync def critical_operation() -> None:\n    \"\"\"Perform critical operation that should never fail.\"\"\"\n    try:\n        await process_critical_data()\n    except Exception:\n        logger.exception(\"Critical operation failed unexpectedly\")\n        raise\n```\n\n### Type Hints and Comments\n\n* Add type hints across public and internal APIs.\n* Comments and docstrings should be in English and explain why, not only what.\n* Use Protocols and TypedDict or pydantic models where appropriate.\n* Avoid excessive literal dict access (for example, using `obj['key']` everywhere); prefer typed structures such as `dataclass`, pydantic models, or `TypedDict` for clearer contracts and better type safety.\n\n### Error Handling\n\n* Keep try-except depth to at most two levels.\n* Catch specific exceptions. Re-raise with context if needed.\n* Prefer explicit None checks and guard clauses over broad exception use.\n\n```python\nimport json\nfrom loguru import logger\n\ndef parse_payload(raw: str) -> dict:\n    \"\"\"Parse payload; return empty dict on known format errors.\"\"\"\n    try:\n        data = json.loads(raw)\n    except json.JSONDecodeError as exc:\n        logger.info(\"Invalid JSON: {err}\", err=str(exc))\n        return {}\n    return data\n```\n\n### Structure and Size\n\n* Avoid nested functions; extract helpers at module level.\n* Keep functions under 200 lines. Split into well-named helpers.\n* Avoid functions with more than 10 parameters; prefer wrapping parameters in a struct or object.\n* Separate concerns: I/O, parsing, business logic, and orchestration.\n\n### Strings and Literals\n\n* Avoid long string literals; wrap lines under 100 characters.\n* Avoid magic numbers and ad-hoc string literals. Centralize constants.\n\n```python\n# constants.py\nDEFAULT_TIMEOUT_S: float = 10.0\nMAX_RETRIES: int = 3\n```\n\n### Boolean Logic\n\n* Be careful with or where 0, empty, or False may be meaningful.\n* Prefer explicit checks:\n\n```python\n# Prefer\nvalue = user_value if user_value is not None else default\n\n# Avoid\nvalue = user_value or default\n```\n\n### Module and Package Layout\n\n* Group agent core, adapters, and utilities into separate modules.\n* Keep public surface small. Delay re-exports in __init__ until stable.\n* If circular dependencies appear, refactor shared contracts to a thin shared module (e.g., interfaces.py or contracts.py).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Guidelines\n\n## Python Programming\n\n### Python Environment\n\n* Package manager: uv\n* Virtual environment: `./python/.venv`\n* Testing command: `uv run pytest`\n\n### Imports\n\n* Avoid inline imports unless required to break a circular dependency.\n* If you import more than three names from a single module, prefer qualified imports:\n  * Prefer: `import pathlib; pathlib.Path, pathlib.PurePath`\n  * Avoid: `from pathlib import Path, PurePath, PurePosixPath, ...`\n* Postpone changes to `__init__` and `__all__` until APIs stabilize.\n* Use TYPE_CHECKING for imports only needed for type hints.\n\n```python\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from mypkg.schemas import AgentConfig\n```\n\n### Runtime Checks\n\n* Avoid excessive use of `getattr`, `hasattr`, and runtime type checks.\n* If an object is a pydantic `BaseModel`, prefer using its validated attributes and type annotations instead of probing attributes at runtime.\n* Rely on pydantic validation, model validators, and type hints; prefer `TypedDict` or `Protocol` for structural typing when appropriate.\n* When runtime checks are necessary, make them explicit, minimal, and well-documented so the reason for the guard is clear.\n\n### Async-First Design\n\n* Prefer asynchronous APIs for I/O-bound work.\n* Use asyncio or anyio; for HTTP, prefer httpx (async client).\n* Ensure clear async boundaries: public APIs and I/O paths should be async.\n* Provide minimal sync adapters only when needed, and document them.\n\n```python\nimport asyncio\nfrom loguru import logger\nimport httpx\n\nasync def fetch_agent_state(url: str, timeout_s: float) -> dict:\n    \"\"\"Fetch agent state from a remote endpoint.\"\"\"\n    async with httpx.AsyncClient(timeout=timeout_s) as client:\n        resp = await client.get(url)\n        resp.raise_for_status()\n        data = resp.json()\n        logger.info(\"Fetched state from {url}\", url=url)\n        return data\n\ndef fetch_agent_state_sync(url: str, timeout_s: float) -> dict:\n    \"\"\"Synchronous adapter. Prefer the async variant.\"\"\"\n    return asyncio.run(fetch_agent_state(url, timeout_s))\n```\n\n### Logging\n\n* Use loguru; placeholders must be {} rather than %.\n* Log key events at info; avoid excessive logging.\n* Do not log sensitive data.\n* Use `logger.exception` sparingly: only for truly unexpected errors that require stack traces for debugging. For expected or recoverable errors, prefer `logger.warning` or `logger.error` with explicit context.\n* Prefer `logger.warning` for recoverable issues, degraded states, or when an operation can continue despite an error.\n\n```python\nfrom loguru import logger\n\ndef process_items(items: list[str]) -> int:\n    \"\"\"Process items and return count.\"\"\"\n    count = len(items)\n    logger.info(\"Processing {count} items\", count=count)\n    # ...\n    logger.info(\"Processed {count} items\", count=count)\n    return count\n\n# Good: expected error, use warning with context\nasync def send_notification(msg: str) -> None:\n    \"\"\"Send notification; log warning if it fails (non-critical).\"\"\"\n    try:\n        await notify_service(msg)\n    except NetworkError as exc:\n        logger.warning(\"Notification failed, continuing: {err}\", err=str(exc))\n\n# Good: unexpected error requiring investigation, use exception\nasync def critical_operation() -> None:\n    \"\"\"Perform critical operation that should never fail.\"\"\"\n    try:\n        await process_critical_data()\n    except Exception:\n        logger.exception(\"Critical operation failed unexpectedly\")\n        raise\n```\n\n### Type Hints and Comments\n\n* Add type hints across public and internal APIs.\n* Comments and docstrings should be in English and explain why, not only what.\n* Use Protocols and TypedDict or pydantic models where appropriate.\n* Avoid excessive literal dict access (for example, using `obj['key']` everywhere); prefer typed structures such as `dataclass`, pydantic models, or `TypedDict` for clearer contracts and better type safety.\n\n### Error Handling\n\n* Keep try-except depth to at most two levels.\n* Catch specific exceptions. Re-raise with context if needed.\n* Prefer explicit None checks and guard clauses over broad exception use.\n\n```python\nimport json\nfrom loguru import logger\n\ndef parse_payload(raw: str) -> dict:\n    \"\"\"Parse payload; return empty dict on known format errors.\"\"\"\n    try:\n        data = json.loads(raw)\n    except json.JSONDecodeError as exc:\n        logger.info(\"Invalid JSON: {err}\", err=str(exc))\n        return {}\n    return data\n```\n\n### Structure and Size\n\n* Avoid nested functions; extract helpers at module level.\n* Keep functions under 200 lines. Split into well-named helpers.\n* Avoid functions with more than 10 parameters; prefer wrapping parameters in a struct or object.\n* Separate concerns: I/O, parsing, business logic, and orchestration.\n\n### Strings and Literals\n\n* Avoid long string literals; wrap lines under 100 characters.\n* Avoid magic numbers and ad-hoc string literals. Centralize constants.\n\n```python\n# constants.py\nDEFAULT_TIMEOUT_S: float = 10.0\nMAX_RETRIES: int = 3\n```\n\n### Boolean Logic\n\n* Be careful with or where 0, empty, or False may be meaningful.\n* Prefer explicit checks:\n\n```python\n# Prefer\nvalue = user_value if user_value is not None else default\n\n# Avoid\nvalue = user_value or default\n```\n\n### Module and Package Layout\n\n* Group agent core, adapters, and utilities into separate modules.\n* Keep public surface small. Delay re-exports in __init__ until stable.\n* If circular dependencies appear, refactor shared contracts to a thin shared module (e.g., interfaces.py or contracts.py).\n","category":"root","tokens":1385}]}