{"id":38011069,"url":"https://github.com/pragmatiks/pragma-sdk","last_synced_at":"2026-04-04T16:09:29.452Z","repository":{"id":332102848,"uuid":"1132749326","full_name":"pragmatiks/pragma-sdk","owner":"pragmatiks","description":"Python SDK for pragma-os. Build providers and manage infrastructure programmatically.","archived":false,"fork":false,"pushed_at":"2026-03-27T17:08:25.000Z","size":424,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T02:42:38.703Z","etag":null,"topics":["ai-infrastructure","api-client","async-python","developer-tools","infrastructure-as-code","platform-engineering","provider-framework","pydantic","python","sdk"],"latest_commit_sha":null,"homepage":"https://docs.pragmatiks.io/sdk/overview","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pragmatiks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-12T11:56:02.000Z","updated_at":"2026-03-27T17:08:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pragmatiks/pragma-sdk","commit_stats":null,"previous_names":["pragmatiks/sdk","pragmatiks/pragma-sdk"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/pragmatiks/pragma-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pragmatiks%2Fpragma-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pragmatiks%2Fpragma-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pragmatiks%2Fpragma-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pragmatiks%2Fpragma-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pragmatiks","download_url":"https://codeload.github.com/pragmatiks/pragma-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pragmatiks%2Fpragma-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-infrastructure","api-client","async-python","developer-tools","infrastructure-as-code","platform-engineering","provider-framework","pydantic","python","sdk"],"created_at":"2026-01-16T19:20:31.274Z","updated_at":"2026-04-04T16:09:29.395Z","avatar_url":"https://github.com/pragmatiks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/wordmark.png\" alt=\"Pragma-OS\" width=\"800\"\u003e\n\u003c/p\u003e\n\n# Pragma SDK\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/pragmatiks/pragma-sdk)\n[![PyPI version](https://img.shields.io/pypi/v/pragmatiks-sdk.svg)](https://pypi.org/project/pragmatiks-sdk/)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n\n**[Documentation](https://docs.pragmatiks.io/sdk/overview)** | **[CLI](https://github.com/pragmatiks/pragma-cli)** | **[Providers](https://github.com/pragmatiks/pragma-providers)**\n\nBuild providers and interact with the pragma-os platform programmatically.\n\n## Quick Start\n\n### Synchronous Client\n\n```python\nfrom pragma_sdk import PragmaClient, Resource\n\nwith PragmaClient() as client:\n    # Apply a resource\n    client.apply_resource(\n        Resource(\n            provider=\"gcp\",\n            resource=\"storage\",\n            name=\"my-bucket\",\n            config={\"location\": \"US\", \"storage_class\": \"STANDARD\"}\n        )\n    )\n\n    # Get resource status\n    bucket = client.get_resource(\"gcp\", \"storage\", \"my-bucket\")\n    print(bucket.outputs)\n```\n\n### Asynchronous Client\n\n```python\nimport asyncio\nfrom pragma_sdk import AsyncPragmaClient, Resource\n\nasync def main():\n    async with AsyncPragmaClient() as client:\n        # Apply a resource\n        await client.apply_resource(\n            Resource(\n                provider=\"gcp\",\n                resource=\"storage\",\n                name=\"my-bucket\",\n                config={\"location\": \"US\", \"storage_class\": \"STANDARD\"}\n            )\n        )\n\n        # Get resource status\n        bucket = await client.get_resource(\"gcp\", \"storage\", \"my-bucket\")\n        print(bucket.outputs)\n\nasyncio.run(main())\n```\n\n## Installation\n\n```bash\npip install pragmatiks-sdk\n```\n\nOr with uv:\n\n```bash\nuv add pragmatiks-sdk\n```\n\n## Features\n\n- **HTTP Clients** - Sync and async clients for the pragma-os API\n- **Provider Authoring** - Build custom providers with type-safe Config and Outputs\n- **Provider Deployment** - Push, build, deploy, and rollback providers programmatically\n- **Dead-Letter Queue** - Inspect and retry failed events for debugging and recovery\n- **Field References** - Reference outputs from other resources dynamically\n- **Testing Harness** - Test provider lifecycle methods locally without deployment\n- **Auto-discovery** - Automatic credential resolution from environment or config files\n\n## Building Providers\n\nDefine resources with typed configuration and lifecycle methods:\n\n```python\nfrom pragma_sdk import Provider, Resource, Config, Outputs, Field\n\ngcp = Provider()\n\nclass BucketConfig(Config):\n    location: Field[str]\n    storage_class: Field[str] = \"STANDARD\"\n\nclass BucketOutputs(Outputs):\n    url: str\n    created_at: str\n\n@gcp.resource(\"storage\")\nclass Bucket(Resource[BucketConfig, BucketOutputs]):\n    async def on_create(self) -\u003e BucketOutputs:\n        # Provision the bucket\n        return BucketOutputs(url=f\"gs://{self.name}\", created_at=\"...\")\n\n    async def on_update(self, previous_config: BucketConfig) -\u003e BucketOutputs:\n        # Handle config changes\n        return self.outputs\n\n    async def on_delete(self) -\u003e None:\n        # Clean up\n        pass\n```\n\n## Field References\n\nReference outputs from other resources:\n\n```python\nfrom pragma_sdk import FieldReference\n\nconfig = AppConfig(\n    database_url=FieldReference(\n        provider=\"postgres\",\n        resource=\"database\",\n        name=\"my-db\",\n        field=\"outputs.connection_url\"\n    )\n)\n```\n\n## Testing Providers\n\nTest lifecycle methods locally with `ProviderHarness`:\n\n```python\nfrom pragma_sdk.provider import ProviderHarness\n\nasync def test_bucket_creation():\n    harness = ProviderHarness()\n\n    result = await harness.invoke_create(\n        Bucket,\n        name=\"test-bucket\",\n        config=BucketConfig(location=\"US\")\n    )\n\n    assert result.success\n    assert \"gs://test-bucket\" in result.outputs.url\n```\n\n## Authentication\n\nCredentials are discovered automatically in this order:\n\n1. Explicit `auth_token` parameter\n2. Context-specific environment variable: `PRAGMA_AUTH_TOKEN_{CONTEXT}` (e.g., `PRAGMA_AUTH_TOKEN_PRODUCTION`)\n3. Generic environment variable: `PRAGMA_AUTH_TOKEN`\n4. Credentials file: `~/.config/pragma/credentials`\n\nThe context is determined by: explicit `context` parameter \u003e `PRAGMA_CONTEXT` env var \u003e CLI config \u003e `\"default\"`.\n\n```python\n# Auto-discover credentials (uses default context)\nclient = PragmaClient()\n\n# Explicit token\nclient = PragmaClient(auth_token=\"sk_...\")\n\n# Use a specific context (checks PRAGMA_AUTH_TOKEN_PRODUCTION first)\nclient = PragmaClient(context=\"production\")\n\n# Require authentication (fail if no token)\nclient = PragmaClient(require_auth=True)\n```\n\n## API Reference\n\n### HTTP Client Methods\n\nBoth `PragmaClient` (sync) and `AsyncPragmaClient` (async) provide the same methods.\n\n#### Resources\n\n| Method | Description |\n|--------|-------------|\n| `list_resources(provider, resource, tags)` | List resources with optional filters |\n| `get_resource(provider, resource, name)` | Get a specific resource |\n| `apply_resource(resource)` | Create or update a resource |\n| `delete_resource(provider, resource, name)` | Delete a resource |\n| `list_resource_types(provider)` | List available resource types from deployed providers |\n\n#### Providers\n\n| Method | Description |\n|--------|-------------|\n| `list_providers()` | List all providers for the current tenant |\n| `push_provider(provider_id, tarball)` | Push provider code and trigger a build |\n| `deploy_provider(provider_id, version)` | Deploy a provider (latest build if no version) |\n| `rollback_provider(provider_id, version)` | Rollback to a previous build version |\n| `delete_provider(provider_id, cascade)` | Delete a provider and associated resources |\n| `get_deployment_status(provider_id)` | Get deployment status for a provider |\n| `list_builds(provider_id)` | List builds for a provider |\n| `get_build_status(provider_id, version)` | Get status of a specific build |\n| `stream_build_logs(provider_id, version)` | Stream logs from a build |\n\n#### Dead-Letter Queue\n\n| Method | Description |\n|--------|-------------|\n| `list_dead_letter_events(provider)` | List dead letter events with optional provider filter |\n| `get_dead_letter_event(event_id)` | Get a dead letter event by ID |\n| `retry_dead_letter_event(event_id)` | Retry a single dead letter event |\n| `retry_all_dead_letter_events()` | Retry all dead letter events |\n| `delete_dead_letter_event(event_id)` | Delete a single dead letter event |\n| `delete_dead_letter_events(provider, all)` | Delete multiple dead letter events |\n\n#### User \u0026 Health\n\n| Method | Description |\n|--------|-------------|\n| `is_healthy()` | Check API health |\n| `get_me()` | Get current authenticated user information |\n\n### Provider Classes\n\n| Class | Description |\n|-------|-------------|\n| `Provider()` | Resource grouping with `@provider.resource()` decorator |\n| `Resource[ConfigT, OutputsT]` | Base class with `on_create`, `on_update`, `on_delete` |\n| `Config` | Base class for resource configuration (Pydantic model) |\n| `Outputs` | Base class for resource outputs (Pydantic model) |\n| `Field[T]` | Type alias for `T | FieldReference` |\n| `ProviderHarness` | Local testing harness |\n\n## Development\n\n```bash\n# Run tests\ntask sdk:test\n\n# Format code\ntask sdk:format\n\n# Type check and lint\ntask sdk:check\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpragmatiks%2Fpragma-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpragmatiks%2Fpragma-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpragmatiks%2Fpragma-sdk/lists"}