Metadata-Version: 2.4
Name: pyprocore
Version: 2.4.0
Summary: A production-ready Python SDK for the Procore REST API.
Author-email: Vibhanshu Mishra <vibhanshumishra72@gmail.com>
Maintainer-email: Vibhanshu Mishra <vibhanshumishra72@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Vibhanshu Mishra
        
        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.
        
Project-URL: Homepage, https://github.com/vibhanshu-mishra/pyprocore
Project-URL: Repository, https://github.com/vibhanshu-mishra/pyprocore
Project-URL: Issues, https://github.com/vibhanshu-mishra/pyprocore/issues
Project-URL: Documentation, https://github.com/vibhanshu-mishra/pyprocore#readme
Project-URL: Changelog, https://github.com/vibhanshu-mishra/pyprocore/blob/main/CHANGELOG.md
Keywords: procore,construction,sdk,python,automation,construction-management,developer-tools,documents,drawings,project-management,oauth,api,rfi,submittals,workflow
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.3
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pydantic>=2.8.2
Requires-Dist: tenacity>=8.5.0
Provides-Extra: async
Requires-Dist: httpx>=0.27.0; extra == "async"
Provides-Extra: dev
Requires-Dist: black>=24.10.0; extra == "dev"
Requires-Dist: coverage>=7.6.0; extra == "dev"
Requires-Dist: flake8>=7.1.0; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: types-requests>=2.32.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Dynamic: license-file

# PyProcore

> Open-source Python SDK and automation toolkit for safe, read-oriented Procore integrations.

[![PyPI](https://img.shields.io/pypi/v/pyprocore.svg)](https://pypi.org/project/pyprocore/)
![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)
[![License](https://img.shields.io/pypi/l/pyprocore.svg)](LICENSE)
[![Tests](https://github.com/vibhanshu-mishra/pyprocore/actions/workflows/tests.yml/badge.svg)](https://github.com/vibhanshu-mishra/pyprocore/actions/workflows/tests.yml)
![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)

PyProcore helps developers, consultants, and construction-tech teams build
Procore integrations without rebuilding OAuth, token refresh, pagination,
retries, typed response parsing, downloads, exports, and local automation
plumbing from scratch.

The SDK is read-oriented and safety-first. It is designed for listing,
retrieving, searching, downloading, exporting, packaging, and validating Procore
project data while keeping write and execution surfaces closed by default.

The latest published stable release is `2.3.0`. Version `2.4.0` is prepared in
this repository but has not yet been published. It adds Project Tools read
coverage, local plugin trust policy reports, OAS catalog and discovery
metadata, integration blueprints, local analytics, an optional FastAPI starter,
and a human-review API maintenance workflow covering drift, impact, migration
plans, draft packs, compatibility contracts, and migration guides.

These features remain read-only, local, or report-oriented. MCP is
discovery-only, Procore tool execution is disabled, and no external AI/model
API is called by default. Maintenance helpers do not fetch remote code/specs,
edit customer code, apply patches, run git, call GitHub, or open pull requests.

## Installation

Install the current stable release:

```bash
python3 -m pip install pyprocore==2.3.0
```

Install optional async HTTP support:

```bash
python3 -m pip install "pyprocore[async]==2.3.0"
```

The prepared `2.4.0` package is available from this checkout only until manual
release publication.

## Quick Start

Create and configure a local `.env` file:

```bash
cp .env.example .env
```

Check your setup and complete OAuth:

```bash
procore-sdk doctor
procore-sdk auth login-url
procore-sdk auth exchange-code YOUR_AUTHORIZATION_CODE
procore-sdk companies
```

Use the object client:

```python
from pyprocore import Procore

client = Procore()

projects = client.projects.list(company_id=123456)
for project in projects:
    print(project.id, project.name)
```

Build a local project context package:

```python
from pyprocore.workflows import build_project_context_package

result = build_project_context_package(
    project_id=352338,
    company_id=4286480,
    output_dir="exports/project-context",
    include=["project", "rfis", "submittals"],
    max_items=100,
)

print(result.summary_path)
```

PyProcore loads `.env` from the current working directory and does not override
environment variables that are already set.

## What You Can Build

### Typed Procore API Access

- Work with typed Pydantic models instead of raw JSON dictionaries.
- Use an object-oriented `Procore` client or function-style service helpers.
- Rely on automatic pagination, retries, token refresh, and custom SDK errors.

### Local Exports And Sync Workflows

- Export supported resources to CSV, JSONL, Markdown, and manifest files.
- Build repeatable local workflow plans for project exports.
- Run dry-run and validation helpers before scheduled automation.

### AI-Ready Local Context Packages

- Package RFIs, submittals, documents, drawings, specs, and project context for
  review workflows.
- Generate local prompt packs, checklists, source indexes, and vector-export
  manifests.
- Keep model selection outside the SDK; no AI provider is called by default.

### Async Read Workflows

- Use `AsyncProcore` for read-oriented async workflows.
- Export and download with conservative concurrency controls.
- Plan async multi-project batches with local validation and dry-run manifests.

### Enterprise Scheduled-Export Planning

- Validate scheduled export configs locally.
- Review token-store safety and credential rotation guidance.
- Use private deployment and production runbook docs for operational planning.

### Plugin Metadata And Local Extension Scaffolding

- Inspect metadata-only plugin manifests and extension-pack files.
- Register trusted in-process hooks only from local application code.
- Generate local plugin developer templates without fetching or installing
  remote plugins.
- Validate local plugin trust policies and metadata-only trust reports without
  installing, importing, or executing plugin code.

### Local OAS Catalog Intelligence

- Inspect a user-provided local OpenAPI/OAS JSON file.
- Classify endpoints as read-only, risky/write, or unknown from metadata.
- Compare endpoint areas to known PyProcore read coverage.
- Compare local specs and plan human-reviewed read-only coverage with the API
  maintenance assistant.
- Scan a user-selected local codebase for PyProcore usage and relate broad
  capability families to optional local OAS drift.
- Build human-review migration plans and optional review artifacts without
  applying patches, running git, or changing customer files.
- Produce JSON or Markdown reports without fetching remote catalogs, generating
  executable tools, editing customer code, calling Procore, or enabling writes.

### Local Discovery Router Metadata

- Search PyProcore capability metadata by intent, such as `overdue rfis`.
- Get ranked route suggestions with reasons and explicit safety boundaries.
- Include local OAS catalog candidates when a local OAS JSON file is provided.
- Keep discovery metadata-only: no SDK execution, no Procore calls, no MCP
  execution, no external AI/model calls, no remote OAS fetch, and no writes.

### Local Integration Blueprints

- Inspect safe templates for sync workers, webhook receivers, read-only APIs,
  dashboard data bridges, scheduled exports, and project health feeds.
- Create local sync-run JSON/JSONL records and sanitized webhook fixtures.
- Run local readiness checks for output paths, env vars, token-store placement,
  webhook secrets, and no-secrets guidance.
- Keep blueprints local-only: no hosted app, no database dependency, no automatic
  scheduler, no Procore calls, no MCP/tool execution, and no write actions.

### Local Project Health Analytics

- Analyze local/exported RFI, submittal, change, and Daily Log records.
- Produce deterministic JSON, Markdown, and CSV summaries for review workflows.
- Combine available signals into a heuristic project health report.
- Keep analytics local-only: no Procore calls, no external AI/model calls, no
  hosted dashboard, no database dependency, and no write actions.

### Optional FastAPI Read API Starter

- Inspect or copy a static FastAPI starter template for read-only backend
  experiments.
- Keep FastAPI and uvicorn outside PyProcore package dependencies.
- Copy local template files only; no app is hosted, no dependencies are
  installed, no Procore calls are made, and no write routes are enabled.

### Deterministic Evals And Regression Checks

- Run local golden eval suites for workflow packages and manifests.
- Compare deterministic baselines and regression reports.
- Score offline model-response fixtures without calling a model.

### MCP Discovery Metadata

- Inspect MCP-style resources, prompts, contracts, snapshots, and reports.
- Inspect the local agent tool registry, local agent API server, agent OpenAPI
  and JSON Schema exports, and replay metadata.
- Validate discovery metadata locally without credentials.
- Keep MCP discovery separate from tool execution.

See the [full feature](docs/features.md) inventory.

## Supported Resource Families

PyProcore supports read-oriented access across these resource families:

- Companies and Projects
- RFIs and Submittals
- Project Tools, Documents, Drawings, Specifications, Photos, and Daily Logs
- Observations, Punch Items, Correspondence, Meetings, Inspections, and Incidents
- Directory, Vendors, Departments, Distribution Groups, and Locations
- Read-only financial, contract, billing, schedule, task, form, coordination
  issue, and action-plan metadata

See [API Coverage](docs/api-coverage.md) for endpoint notes, permission context,
and live-verification limitations.

## CLI Overview

Common commands:

```bash
procore-sdk doctor
procore-sdk companies
procore-sdk projects
procore-sdk rfis --project 352338
procore-sdk submittals --project 352338
procore-sdk project-context --project 352338 --company 4286480
procore-sdk scheduled-export dry-run examples/configs/scheduled_export_client_credentials.json
procore-sdk evals run
procore-sdk mcp validate
procore-sdk catalog summarize examples/catalog/fake_procore_oas.json
procore-sdk discovery search "overdue rfis"
procore-sdk analytics project-health --rfis examples/analytics/fake_rfis.json --format markdown
procore-sdk templates show fastapi-read-api
procore-sdk templates copy fastapi-read-api --output-dir ./tmp-fastapi-read-api --dry-run
```

See [CLI Usage](docs/cli.md) for the full command reference.

## Safety Model

PyProcore is intentionally conservative:

- PyProcore is read-oriented.
- Workflow helpers write local files, not Procore data.
- Procore tool execution is disabled.
- MCP is discovery-only.
- No external AI/model APIs are called by default.
- Plugin manifests, configs, extension packs, and scaffolds are metadata or
  templates only.
- No Procore create, update, delete, upload, approve, submit, payment, or other
  mutation actions are enabled.

Never commit `.env` files, OAuth tokens, token stores, Authorization headers, or
private project data.

## Documentation Site

| Topic | Link |
| --- | --- |
| Documentation Home | [docs/index.md](docs/index.md) |
| Getting Started | [docs/getting-started.md](docs/getting-started.md) |
| Authentication | [docs/authentication.md](docs/authentication.md) |
| Complete Feature Inventory | [docs/features.md](docs/features.md) |
| API Coverage | [docs/api-coverage.md](docs/api-coverage.md) |
| Workflows | [docs/workflows.md](docs/workflows.md) |
| Docker Automation | [docs/automation/docker.md](docs/automation/docker.md) |
| CI Automation | [docs/automation/ci.md](docs/automation/ci.md) |
| Docker Examples | [examples/docker](examples/docker) |
| Async Client | [docs/async-client.md](docs/async-client.md) |
| AI Workflows | [docs/ai-workflows.md](docs/ai-workflows.md) |
| Agent API | [docs/agent-api.md](docs/agent-api.md) |
| MCP Discovery | [docs/mcp.md](docs/mcp.md) |
| Plugins | [docs/plugins.md](docs/plugins.md) |
| Analytics Recipes | [docs/analytics-recipes.md](docs/analytics-recipes.md) |
| FastAPI Starter | [docs/fastapi-starter.md](docs/fastapi-starter.md) |
| Golden Evals | [docs/evals.md](docs/evals.md) |
| Release Guide | [docs/release.md](docs/release.md) |
| Roadmap | [docs/roadmap.md](docs/roadmap.md) |
| Features | [docs/features.md](docs/features.md) |
| Examples | [examples/README.md](examples/README.md) |
| Project Status | [docs/project-status.md](docs/project-status.md) |
| GitHub Labels | [docs/github-labels.md](docs/github-labels.md) |

Run `make docs-build` to build the MkDocs site or `make docs-serve` to preview
it locally.

## Prepared For v2.4.0

`v2.4.0` is an additive, backward-compatible release candidate. Highlights:

- Read-only Project Tools metadata helpers.
- Local plugin trust policies and compatibility reports.
- Local OAS catalog, discovery routing, integration blueprints, analytics
  recipes, and an optional copied FastAPI starter.
- Human-review API drift, codebase impact, migration planning, PR draft,
  compatibility contract, and migration-guide reports.
- Examples through `334` and corresponding mocked/local tests.

Detailed release history lives in [CHANGELOG.md](CHANGELOG.md),
[Project Status](docs/project-status.md), and [Roadmap](docs/roadmap.md).

## Contributing and Support

Contributions, issues, and feature requests are welcome. Start with
[CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md),
[SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## Security

Do not paste or commit Procore client secrets, access tokens, refresh tokens,
Authorization headers, `.env` files, token stores, or private project data. See
[SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).

Maintainers can run `make secret-check` and `make quality-check` before release
or documentation changes.

## License

PyProcore is released under the [MIT license](LICENSE).

## Disclaimer

PyProcore is an independent open-source project. It is not affiliated with,
endorsed by, or supported by Procore Technologies. For official Procore product
support, use Procore's support channels.
