pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "toolsconnector"
version = "0.3.21"
description = "A foundational primitive for standardizing external API tool connections — for both traditional applications and AI agents."
readme = "README.md"
license = "Apache-2.0"
requires-python = ">=3.9"
authors = [{ name = "Sachin Shelke", email = "sachin.worldnet@gmail.com" }]
maintainers = [{ name = "Sachin Shelke", email = "sachin.worldnet@gmail.com" }]
keywords = [
    "api", "connectors", "http", "rest",
    "agent", "ai", "llm", "mcp", "tools", "tool-use",
    "integration", "integrations",
    "langchain", "openai",
    "async", "httpx", "pydantic",
]
classifiers = [
    # PEP 301 Trove classifiers — self-declared metadata shown on PyPI.
    # See https://pypi.org/classifiers/ for the canonical vocabulary.
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Intended Audience :: System Administrators",
    # The License classifier was intentionally dropped — PEP 639 replaced it
    # with the top-level `license = "Apache-2.0"` expression at line 10.
    # Having both triggers a PyPI warning (duplicate metadata).
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Operating System :: OS Independent",
    "Environment :: Web Environment",
    "Topic :: Software Development :: Libraries",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Internet :: WWW/HTTP",
    "Typing :: Typed",
]
dependencies = [
    "pydantic>=2.0,<3.0",
    "httpx>=0.25.0,<1.0",
    "docstring-parser>=0.15,<1.0",
    "eval_type_backport>=0.2.0; python_version < '3.10'",
]

[project.urls]
Homepage = "https://toolsconnector.github.io"
Documentation = "https://toolsconnector.github.io"
Repository = "https://github.com/sachinshelke/ToolsConnector"
Issues = "https://github.com/sachinshelke/ToolsConnector/issues"
Changelog = "https://github.com/sachinshelke/ToolsConnector/blob/main/CHANGELOG.md"

[project.optional-dependencies]
# --- Connectors: Communication ---
gmail = ["google-api-python-client>=2.0", "google-auth>=2.0", "google-auth-oauthlib>=1.0"]
slack = []
discord = []
outlook = []
teams = []
twilio = []
telegram = []

# --- Connectors: Code Platforms ---
github = []
gitlab = []

# --- Connectors: Project Management ---
jira = []
asana = []
linear = []
trello = []

# --- Connectors: Knowledge ---
notion = []
confluence = []

# --- Connectors: CRM / Support / ERP ---
hubspot = []
salesforce = []
zendesk = []
freshdesk = []
intercom = []
odoo = []  # Odoo / OpenERP -- JSON-RPC over httpx (core), no extra deps

# --- Connectors: Finance ---
stripe = []
plaid = []

# --- Connectors: Marketing ---
sendgrid = []
mailchimp = []
linkedin_leads = []
contactout = []
lusha = []

# --- Connectors: Productivity (Google) ---
gsheets = []
gdocs = []
gtasks = []

# --- Connectors: Social ---
linkedin = []
x = []
medium = []

# --- Connectors: Storage ---
gdrive = ["google-api-python-client>=2.0", "google-auth>=2.0"]
gcalendar = ["google-api-python-client>=2.0", "google-auth>=2.0"]
s3 = []

# --- Connectors: Database ---
supabase = []
mongodb = []
airtable = []
firestore = []
redis = []

# --- Connectors: AWS ---
ec2 = []
alb = []
route53 = []
acm = []
cloudwatch = []
iam = []
secrets_manager = []
rds = []
lambda_connector = []

# --- Connectors: DevOps ---
datadog = []
pagerduty = []
vercel = []
cloudflare = []
dockerhub = []

# --- Connectors: AI/ML ---
openai = []
anthropic = []
pinecone = []
huggingface = []
gemini = []
cohere = []
mistral = []
groq = []

# --- Connectors: Analytics ---
mixpanel = []
segment = []

# --- Connectors: Message Queue ---
sqs = []
cloudfront = []
ecr = []
ecs = []
rabbitmq = []

# --- Connectors: Security ---
okta = []
auth0 = []

# --- Connectors: Productivity ---
calendly = []
figma = []

# --- Connectors: E-commerce ---
shopify = []

# --- Connectors: Custom ---
webhook = []

# --- Protocol adapters ---
graphql = ["gql>=3.4", "aiohttp>=3.8"]
soap = ["zeep>=4.2"]
grpc = ["grpcio>=1.50", "protobuf>=4.0"]
websocket = ["websockets>=12.0"]

# --- KeyStore extras ---
vault = ["hvac>=1.0"]
aws-keystore = ["boto3>=1.28"]

# --- Storage extras ---
s3-storage = ["boto3>=1.28"]
gcs-storage = ["google-cloud-storage>=2.0"]

# --- Serve layer ---
mcp = ["mcp>=1.0"]
rest = ["starlette>=0.27", "uvicorn>=0.23"]

# --- Category bundles ---
google = ["toolsconnector[gmail,gdrive,gcalendar,gsheets,gdocs,gtasks]"]
microsoft = ["toolsconnector[outlook,teams]"]
communication = ["toolsconnector[gmail,slack,discord,telegram,twilio]"]
project-mgmt = ["toolsconnector[jira,asana,linear,trello]"]
databases = ["toolsconnector[supabase,mongodb,airtable,firestore,redis]"]
devops = ["toolsconnector[datadog,pagerduty,vercel,cloudflare,dockerhub]"]
ai = ["toolsconnector[openai,anthropic,pinecone,huggingface,gemini,cohere,mistral,groq]"]
crm = ["toolsconnector[hubspot,salesforce,zendesk,freshdesk,intercom]"]
publishers = ["toolsconnector[linkedin,x,medium]"]

# --- AWS bundles ---
aws-deploy = ["toolsconnector[ecs,ecr,cloudfront,alb,route53,acm,s3,cloudwatch]"]
aws-infra = ["toolsconnector[ec2,iam,secrets_manager]"]
aws-monitor = ["toolsconnector[cloudwatch]"]
aws-data = ["toolsconnector[s3,sqs,rds]"]
aws = ["toolsconnector[aws-deploy,aws-infra,aws-monitor,aws-data,lambda_connector]"]

# --- Agent orchestrator ---
orchestrator = ["anthropic>=0.40.0", "pyyaml>=6.0", "rich>=13.0"]

# --- Development ---
dev = [
    "pytest>=7.0",
    "pytest-asyncio>=0.21",
    "pytest-cov>=4.0",
    "respx>=0.20",
    "vcrpy>=6.0",
    "ruff>=0.1",
    "mypy>=1.5",
    "bandit>=1.7",
    "pip-audit>=2.6",
    "pre-commit>=3.5",
]

# --- Everything ---
all = [
    "toolsconnector[gmail,slack,discord,github,gitlab,notion,jira,linear]",
    "toolsconnector[gdrive,gcalendar,s3,outlook,teams,confluence,asana]",
    "toolsconnector[hubspot,salesforce,stripe,twilio,sendgrid,mcp,rest]",
    "toolsconnector[cloudfront,ecr,ecs,ec2,alb,route53,acm]",
    "toolsconnector[cloudwatch,iam,secrets_manager,rds,lambda_connector]",
    "toolsconnector[linkedin,linkedin_leads,x,medium]",
]

[project.scripts]
tc = "toolsconnector.serve.cli:main"

[project.entry-points."toolsconnector.connectors"]
# Connectors register here for CLI/serve discovery
# gmail = "toolsconnector.connectors.gmail:Gmail"

[tool.hatch.build.targets.wheel]
packages = ["src/toolsconnector"]
# Include the PEP 561 marker so downstream mypy/pyright pick up our inline
# type hints without needing a separate `toolsconnector-stubs` package.
include = ["src/toolsconnector/py.typed"]

[tool.hatch.build.targets.sdist]
include = [
    "src/",
    "tests/",
    "docs/",
    "examples/",
    "README.md",
    "CHANGELOG.md",
    "CONTRIBUTING.md",
    "LICENSE",
    "pyproject.toml",
]

[tool.ruff]
src = ["src"]
line-length = 100
target-version = "py39"

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
# Rules we deliberately opt out of:
#
# PEP 604 migration (Py 3.10+): blocked by our Python 3.9 target.
#   UP007 / UP045
#
# Style-only suggestions (not bugs; keep the rule set focused on correctness):
#   E501   — long lines; we prefer readable docstrings with full URLs
#   B904   — `raise X` without `from` inside except; stylistic
#   SIM108 — ternary vs if/else block; stylistic
#   SIM102 — collapsible nested if; stylistic
#   SIM105 — contextlib.suppress vs try/except pass; stylistic
#   B024   — abstract base class without abstract method
#            (BaseConnector is intentionally an ABC with optional overrides)
#   B027   — empty method without @abstractmethod (same reason)
#   TC001/TC002/TC003 — "move to TYPE_CHECKING block"; minor import-time
#            savings, not bugs, and fighting ruff here inflates diffs
#
# Real bugs we still enforce: F-rules (unused imports/vars, broken f-strings),
# E-rules (syntax), N-rules (naming except A002 on connectors), UP-rules
# (other pyupgrade), A-rules (builtin shadowing), B-rules (other bugs),
# I-rules (import order).
ignore = [
    "UP007",  # non-pep604-annotation-union      (Py 3.9 compat)
    "UP045",  # non-pep604-annotation-optional   (Py 3.9 compat)
    "E501",   # line-too-long                    (docstring URLs, SQL, XML)
    "B904",   # raise-without-from-inside-except (stylistic)
    "SIM108", # if-else-block-instead-of-if-exp  (stylistic)
    "SIM102", # collapsible-if                   (stylistic)
    "SIM105", # suppressible-exception           (stylistic)
    "B024",   # abstract-base-class-without-abstract-method (BaseConnector pattern)
    "B027",   # empty-method-without-abstract-decorator
    "TC001",  # typing-only-first-party-import
    "TC002",  # typing-only-third-party-import
    "TC003",  # typing-only-standard-library-import
]

# Per-file carve-outs for things that are legitimately not bugs:
[tool.ruff.lint.per-file-ignores]
# Connectors intentionally mirror upstream API argument names (e.g. `type`,
# `filter`, `format`, `range`) to match the vendor's public contract.
"src/toolsconnector/connectors/**/*.py" = [
    "A001",   # module-level variable shadows builtin (API parity)
    "A002",   # argument shadows builtin            (API parity)
    "A004",   # import shadows builtin              (API parity)
    "N815",   # mixedCase class scope var           (mirrors vendor JSON schema)
]

# The error hierarchy intentionally defines `ConnectionError` and
# `TimeoutError` classes that shadow the Python builtins. This is the same
# pattern requests, httpx, and urllib3 use — a typed exception hierarchy
# with richer context (connector name, retry_eligible, etc.). The shadowing
# is deliberate; re-exports happen in errors/__init__.py and usage from
# runtime/transport/http.py.
"src/toolsconnector/errors/**/*.py" = ["A001", "A004"]
"src/toolsconnector/runtime/transport/**/*.py" = ["A004"]

# _discovery.py delays the errors import to break a circular dependency
# (errors → serve → _discovery → errors). The late import is intentional.
"src/toolsconnector/serve/_discovery.py" = ["E402"]

# webapp/ — the Flask UI uses a few patterns that don't fit ruff's defaults
# but are intentional and documented inline:
#
# - N806: `_CAT_ICONS` and `_CAT_COLORS` are uppercase function-local CONSTANTS
#   (lookup tables). Treating them as constants makes their immutability
#   intent obvious to readers; renaming to lowercase would mislead.
# - E731: `_BF = lambda d: ...` in tool_metadata.py — compact one-line URL
#   helper that's used hundreds of times in a flat data dict. A `def` would
#   pad the file by ~3 lines for no readability gain.
# - E402: webapp/docs_agent.py has a sys.path.insert() before importing httpx
#   so `python webapp/docs_agent.py` works without installing the package.
"webapp/app.py"            = ["N806"]
"webapp/tool_metadata.py"  = ["E731"]
"webapp/docs_agent.py"     = ["E402"]

[tool.mypy]
python_version = "3.9"
strict = true
warn_return_any = true
warn_unused_configs = true
mypy_path = "src"

# ── Per-module mypy relaxations ───────────────────────────────────────────
#
# As of v0.3.x mypy reports ~509 errors across the codebase. ~471 of those
# live in `connectors/`, where strict typing fights vendor-API JSON shape
# (every endpoint returns `dict[str, Any]` whose nested keys aren't
# discoverable until runtime). The remaining ~54 are in core modules
# (serve/runtime/codegen) and are tractable in a focused triage session.
#
# Strategy: keep `strict = true` as the default but loosen on per-module
# basis for code where strict typing isn't pragmatic. Goal: drive the
# enforced surface to zero errors so the CI mypy job can flip from
# `continue-on-error: true` to required.

# Connectors are vendor-API mappers — relax strict mode.
# Each connector handles dict[str, Any] payloads from its tool's REST API,
# which loses meaningful type info at the JSON parse boundary. Strict here
# would produce ~470 errors of type `[no-any-return]` and `[type-arg]` that
# don't represent real bugs — they represent "this dict's shape is the
# vendor's contract, not ours." Type-check connectors at the loose level
# (catches use-before-define, unreachable code, obvious mistakes) but not
# the type-flow rules.
[[tool.mypy.overrides]]
module = "toolsconnector.connectors.*"
disallow_untyped_defs = false
disallow_incomplete_defs = false
disallow_any_unimported = false
disallow_any_generics = false
warn_return_any = false
no_implicit_optional = false

# 3rd-party libraries that ship without type stubs. These are all OPTIONAL
# dependencies behind extras — mypy can't see them when the extras aren't
# installed. Marking them as `ignore_missing_imports` removes the false
# positives without weakening real type checks elsewhere.
[[tool.mypy.overrides]]
module = [
    "cryptography.*",
    "yaml",
    "websockets",
    "starlette.*",
    "mcp.*",
    "langchain_core.*",
    "uvicorn",
]
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]

[tool.coverage.run]
source = ["src/toolsconnector"]
branch = true
# Ignore generated / vendor code from coverage. Adjust as the codebase grows.
omit = [
    "*/tests/*",
    "*/__init__.py",
]

[tool.coverage.report]
# Don't fail the build if coverage drops — it's informational until we
# choose a floor. pytest-cov's `--cov-fail-under=N` is the enforcement flag.
show_missing = true
skip_covered = false
precision = 1
exclude_lines = [
    "pragma: no cover",
    "if TYPE_CHECKING:",
    "raise NotImplementedError",
    "\\.\\.\\.",
    "def __repr__",
]