Lightbulb developer docs

Build with Lightbulb

published

One typed operating model through Python, MCP, and the hosted platform.

The SDK defines Business Process Primitives, Golden Operating Loops, departments, policies, budgets, Projects and Company Blueprints. Agents decide when to use them. Spring authorizes hosted work. Connector Runtime performs the approved provider operation.

• Install and verify
• Python reference
• MCP reference

Install the published package

published

Use Python 3.10–3.13 and an isolated environment. Pin the version documented as published.

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install "lightbulb-sdk==0.25.6"
lightbulb version

lightbulb setup
lightbulb whoami
lightbulb tools --count-only

Installation and local declarations work without AWS. Device login, hosted reads, approvals and provider calls require an available control plane and the relevant configured account.

Verify and upgrade

published

Check the installed artifact before investigating a host or provider failure.

python -m pip show lightbulb-sdk
python -m pip check
lightbulb version
lightbulb --help
lightbulb tools --filter approval

1. Record the current version and keep an exact pin in your project lockfile.
2. Read the target release notes, stability policy and migration guidance.
3. Upgrade in a new environment and run your persisted-document and integration acceptance checks.
4. Promote the lockfile and restart MCP hosts so subprocesses load the upgraded package.

python -m pip install --upgrade "lightbulb-sdk==0.25.6"
python -m pip check
lightbulb version

CLI and entry points

published

Inspect your installation and perform scoped platform operations.

Use --help for exact installed options. setup --no-write previews configuration, --target chooses a supported host, and --url selects an enabled control-plane origin. Remote origins require HTTPS.

Authentication and company scope

published

Authenticate, then select an authorized company and project.

from lightbulb.core import device_login
from lightbulb.hosted import LightbulbClient

BASE_URL = "https://agents.lightbulbpartners.com"
auth, _ = device_login(BASE_URL, client_id="my-integration")
client = LightbulbClient(BASE_URL, auth=auth)
identity = client.whoami()
print(identity)

• Device login keeps passwords and MFA in the browser. Cached sessions remain scoped to their authenticated identity.
• A Tenant Connector may be narrowed to a company or user. Possessing its reference does not authorize it.
• The control plane reauthorizes tenant, company, project and approval scope. Model output cannot supply that authority.
• Unattended hosts need a renewable service identity. Verify the same identity and company/project access after refresh.

Choose an MCP profile

published

Expose the capabilities a host needs while preserving their approval boundaries.

The setup wizard selects adaptive. Its four tools find capabilities, describe an exact schema, invoke a declared read, or request an action with conservative effect annotations. The profile avoids loading the full catalog into every model context.

LIGHTBULB_MCP_PROFILE=adaptive lightbulb tools --count-only
LIGHTBULB_MCP_PROFILE=adaptive lightbulb-mcp

$env:LIGHTBULB_MCP_PROFILE = "adaptive"
lightbulb tools --count-only
lightbulb-mcp

• Search documented MCP tools

Connect Claude Code, Codex or Cursor

published

Each local host runs the installed stdio server under your Lightbulb identity.

lightbulb setup --target claude-code-user
# Inspect other supported targets:
lightbulb setup --help

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com",
        "LIGHTBULB_MCP_PROFILE": "adaptive"
      }
    }
  }
}

• Claude Code and Cursor use their supported MCP configuration files. The wizard preserves unrelated entries and creates backups.
• Codex setup writes the supported MCP configuration and Lightbulb plugin integration. Inspect it with --no-write.
• Restart the host after an upgrade. Its environment must find the same executable.
• Reserve stdout for the MCP protocol and use stderr or host logs for diagnostics.

Hosted MCP and ChatGPT

published

Hosted MCP is an optional account-connected entry point.

Use the Lightbulb app or hosted endpoint supplied by your deployment. Calls follow the authenticated user’s company and approval policies. Local stdio configuration does not configure the hosted server, and a hosted connection does not install the Python SDK.

Continuum context and local work

published

Retain scoped working history without treating context as authorization.

Supported hooks open or resume a Context Space, retrieve a bounded relevant pack and checkpoint session events. Searchable retained history does not increase a provider model’s native context window.

• Tool capture is off by default and needs a reviewed redaction/retention policy.
• Rename-stable company/project references are reauthorized on each invocation.
• Export, archive and deletion use explicit scoped lifecycle controls. Destructive controls are not delegated to the model-facing catalog.
• User-visible local working files and hidden managed state have different roles. Keep managed internals out of ordinary file sharing.

Stability and namespaces

published

Contract stability and live capability certification are separate.

from lightbulb.core import JwtAuth, PermissionDenied
from lightbulb.hosted import LightbulbClient, AsyncLightbulbClient
from lightbulb.runtime import BusinessProcessPrimitive, ExecutablePrimitiveRuntime

The root package is a lazy compatibility facade. Import new functionality from its owning module or a curated namespace. The obsolete lightbulb.sdk facade from older candidates is no longer the current interface.

• Declared public exports
• Stability policy

Sync and async clients

published

Preserve the same authenticated scope in either client.

from lightbulb.core import JwtAuth
from lightbulb.hosted import AsyncLightbulbClient

async def read_identity(auth: JwtAuth):
    async with AsyncLightbulbClient(
        "https://agents.lightbulbpartners.com", auth=auth
    ) as client:
        return await client.whoami()

Hot paths are async-native; long-tail methods may be thread-forwarded compatibility methods. The reference records the implementation mode. Await documented async methods and use the async client’s context manager to close it. The synchronous client does not implement a context-manager protocol. A property or synchronous helper on the async class is not awaitable.

• Client signatures and methods

Errors and retries

published

Classify a failure before deciding whether a retry is safe.

Hosted clients accept an auth_refresh callback. Refreshed credentials do not prove that a previous write failed. Ambiguous effects remain unresolved until their recovery contract completes.

Business Process Primitives

published

Define reusable business mechanics with typed input, output, risk and recovery.

1. Inspect the owning module and exact versioned contract.
2. Declare required Tools, effect classification, approval rules, events and evidence.
3. Validate and simulate locally with external effects disabled.
4. Publish the immutable definition digest and request the exact hosted run.
5. Observe terminal business evidence; provider acceptance may not complete the outcome.

Catalog entries are descriptive metadata. Executable behavior lives behind BusinessProcessPrimitive. Neither creates another credential, persistence or effect authority.

• Primitive/runtime API
• Custom projects

Golden Operating Loops

published

Compose primitives into a bounded lifecycle with a measurable outcome.

A loop declares its trigger, state machine, terminal outcomes, approvals, effects, evidence, recovery, metrics, budgets and canonical implementation. Agents, SDK, MCP and the optional ChatGPT app project the same run identity.

• Retain the immutable definition digest with the run.
• Separate declaration/preview from hosted start and resume.
• Represent approval waits, partial execution and ambiguous outcomes explicitly.
• A Spring-owned certificate for the exact version is required before promising a certified customer outcome.

Departments and Company Blueprints

published

Compose operating responsibilities, policies, budgets and loops into a company.

Departments group loops, roles, policies, budgets and metrics. Blueprints compile into the central operator/cadence catalog without introducing another runtime or authorization model.

The module index supplies exact types and signatures. This responsibility map does not certify every provider deployment.

Projects, workflows and artifacts

published

Bind work to an authorized Project and retain lifecycle evidence.

• Validate the work packet and company/project access before hosted start.
• Use immutable definitions and explicit run references.
• Retain scoped artifact references and typed results without copying unrestricted provider payloads into public metadata.
• Inspect actual approval tasks and execution proofs before consequential work.
• Recover duplicate delivery and restarts with stable idempotency identities.

• Project/artifact API
• Custom project contracts

Run the company worker

published

Persist the read → ingest → decide → approve → execute → reconcile journey.

lightbulb-company-worker \
  --bundle /etc/lightbulb/company-bundle.json \
  --sources /etc/lightbulb/company-sources.json \
  --growth-config /etc/lightbulb/company-growth.json \
  --company-id "$COMPANY_ID" \
  --worker-ref company-worker-01 \
  --receipt-key-file /run/secrets/company-receipts \
  --receipt-key-id company-receipts-v1 \
  --register

1. Authenticate a stable, renewable identity against an enabled control plane.
2. Compile a cadence bundle and bind explicit company-owned sources, target records and provider identities.
3. Create a private receipt key file containing at least 32 random bytes. Keep it stable across restarts and outside model inputs.
4. Open the protected cost, demand, listing and content records through the central operator surface.
5. Use --once for a supervised invocation, then run the host under a process supervisor.

• Registration does not resume an operator-paused company.
• Daily intake starts at UTC midnight and consumes closed days in order.
• Signed journals bind scope, reads, ingestion and watermarks. Unsigned checkpoint edits cannot manufacture completed work.
• Claims, leases and stable idempotency recover interruptions without silently repeating completed effects.

• Complete setup and source bindings

Prepare and inspect company operations

published

Validate configuration offline and inspect authenticated operational evidence when a host is available. These additions require 0.24 or later.

Offline preflight runs the same configuration validator used by the company worker before authentication. It does not certify permissions, connected accounts, protected engine records or a deployment.

lightbulb-company-worker --source-template
lightbulb-company-worker --bundle company-bundle.json --sources company-sources.json --preflight --report-html preflight.html

from lightbulb.company_preflight import source_template
from lightbulb.company_recurring_observations import RecurringObservationBinding

sources = [RecurringObservationBinding.model_validate(row) for row in source_template()]
job = sources[0].job(start="2026-10-01T00:00:00Z", end="2026-10-02T00:00:00Z")
assert job.lane == "governed_read"
assert job.arguments["limit"] == 100
print("Offline source contract validated; account ownership remains unchecked.")

On an enabled host, use --status with the normal bundle, sources, company, worker and receipt-key arguments. --report-html status.html renders a static report. This reads authenticated journals without claiming work or approving actions. Heartbeats, backlog, missing daily windows, period acceptance and unresolved decisions are projected; per-unit pending approval age and unreconciled units come from authenticated journals. Legacy missing timestamps and workspace quarantine remain explicitly unknown.

CompanySourceCensus separates operator inventory assertions, reconciliation evidence references and declared source coverage. It never certifies that all external liabilities exist in Lightbulb. HistoricalCorrection records a permanent hold against an affected economic period before replacement intake and recomputation. Original effects and records remain; paused or incomplete budget units cannot continue using that period.

These operator helpers are Beta. Pin the SDK minor version. Repository maintainers can run python lightbulb-sdk/scripts/verify_sdk_offline.py --output-dir codex-scripts/sdk-offline-evidence from any CI system. No GitHub Actions dependency is required.

Trusted intake and attribution

published

Credit a marketing touch only after verifying its source evidence.

• Caller-supplied provenance hashes are not independent verification. The trusted host binds request, result, journal, row and identity mapping.
• Attribution re-verifies touches and replays settled business revenue. Unknown identities remain explicit.
• PostHog cursors bind query/scope; overlap is deduplicated by event ID. Changed duplicates and non-progress are refused.
• Completion requires a terminal page. Bounded read completion cannot prove the absence of late or backdated events.

Costs, growth periods and CAC

published

Aggregate economic evidence through the protected company cost register.

• Replay settled business revenue instead of adding unverified sales totals.
• Post media and inference costs into the protected register without adding a second projected total.
• Require daily source coverage and complete attribution lookback.
• Verify first-purchase history before CAC. Zero acquisitions leaves CAC undefined.
• Allocate content costs explicitly and retain unallocated amounts.
• Close the register with replayed bank coverage, including explicit zero-outflow evidence.

• Growth data contracts

Demand pacing and reallocation

published

Turn accepted evidence into exact governed provider requests.

1. Record spend against durable demand reservations. Overspend stops new reservations.
2. Bind exact account/campaign pause targets before enabling controls.
3. Qualify receiving channels with independently verified incremental returns; missing evidence produces a hold.
4. Read fresh targets/currency and create exact per-unit approvals.
5. Complete decreases/pauses before increases, retaining results for reconciliation.

Unfinished writes recheck the decision period and evidence deadline. Expired decisions retain partial proofs and require a fresh decision. Pending approvals do not block unrelated cadence.

Pagination and closure

published

Process the complete scoped inventory before declaring closure.

Immutable engine-state snapshots preserve exact tenant, company, project and actor across continuations. Cadence and closure consumers traverse all pages.

Use all-page helpers where documented. Partition larger declared periods/sources through supported contracts. Never treat the first page as the entire company.

BYOK and provider custody

published

Use scoped references and current custody checks for provider administration.

• Model execution and native OpenAI administration use governed control-plane paths. Workers receive references instead of raw provider keys.
• Document AI keeps Google service-account credentials inside the same custody boundary.
• Object ownership is checked independently of key custody, including references inside model requests.
• Unknown legacy objects require controlled migration/recreation. Knowing an ID cannot claim ownership.
• Retain authentic provider result IDs, sanitized usage and recovery evidence. Synthetic internal IDs cannot prove provider ownership.

Constrained workspace execution

published

Use the governed local broker when the deployment enables it.

The broker owns sandbox images, network policy, process admission, limits, cancellation and artifact reconciliation. Work starts from a bounded canonical workspace copy. Conflicting, escaped or oversized output is rejected.

• Workspace and Cursor readiness

Approvals, evidence and recovery

published

A proposal, listed tool or local test does not authorize a live effect.

1. Resolve authenticated actor and company/project scope.
2. Validate exact capability version, target, amount and policy.
3. Obtain the configured approval.
4. Dispatch through the canonical Connector Tool binding with stable request identity.
5. Observe independent evidence and reconcile an ambiguous response.

Security fixes may immediately close unsafe compatibility paths. Do not bypass refused legacy cost projections, unsigned touches or unknown provider objects through raw APIs.

Security and deployment readiness

published

Keep credentials and authority in their intended boundaries.

• Use HTTPS for remote origins and verify browser login redirects.
• Protect receipt keys and connector credentials; exclude them from repositories and model-readable inputs.
• Log sanitized references/error codes with scope preserved.
• Separate local package acceptance from provider, Docker/kernel and deployed integration certification.
• Retain Beta, Private and Quarantined labels until the corresponding contract/certification changes.

Troubleshooting

published

Start with version, identity and the exact failed stage.

Release status and automatic updates

published

Verify package, source and documentation identities together.

The coordinated release builds an immutable source revision, publishes accepted archives, checks PyPI hashes, updates the public source snapshot and sends the same documentation bundle to this site. Completion requires a matching receipt and documentation digest on the public site.

Main-branch changes refresh candidate docs. Version tags and the protected publication environment control public releases. Installed projects remain pinned until their owners upgrade.

• PyPI package
• Public manifest
• Complete reference download

Reference and guides

published

Exact signatures in the index; complete operating contracts in the guides.

• Python reference
• MCP reference
• Versioned browser
• Machine-readable reference
• Complete Markdown reference
• Package README
• MCP integration
• Custom projects
• Stability
• Company operations
• Company data contracts
• Execution readiness

The index distinguishes public symbols, explicit exports, dynamic compatibility methods and MCP projections. Coverage metadata states static-analysis limits. Source-declared presence does not imply execution permission.

Company intelligence

published

Read business evidence, decide what to do, and track the outcome.

Start with the persisted company chains, build product, money and skilled-labour documents, then bring their findings into a weekly review and a board pack. The guide walks through Python, command-line and MCP use, adoption and sync, and the review-to-decision-to-work-item loop.

Document seals and review outcomes describe recorded evidence. Governed execution still requires the appropriate authority and project binding; a report alone does not prove a live action occurred.

• Company intelligence guide
• Intelligence definitions and worked examples

Get help

published

Share enough sanitized evidence to reproduce a problem.

• Package/Python versions and operating system.
• Selected MCP profile or SDK entry point.
• Operation, timestamp, sanitized error and request/run reference.
• Failed stage: install, authenticate, read, ingest, decide, approve, execute or reconcile.
• Minimal example without secrets, customer content or private identifiers.

• Contact Lightbulb Partners
• Package release history