Metadata-Version: 2.4
Name: langchain-sibfly
Version: 0.1.0
Summary: An integration package connecting SibFly (measured ground motion per US address, from NASA InSAR) and LangChain
Author-email: SibFly <support@sibfly.com>
License: MIT
Project-URL: Homepage, https://sibfly.com
Project-URL: Repository, https://github.com/james-sib/langchain-sibfly
Project-URL: Source Code, https://github.com/james-sib/langchain-sibfly/tree/master/langchain_sibfly
Keywords: langchain,sibfly,insar,ground-motion,subsidence,geospatial,nasa,agents,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core<0.4,>=0.3
Requires-Dist: httpx>=0.27
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

# langchain-sibfly

LangChain integration for [SibFly](https://sibfly.com) — **measured ground motion for any US address**.

Give it a US address (or lat/lon) and it tells your agent how fast the ground is
**sinking or rising, in mm/year**, measured from NASA OPERA Sentinel-1 satellite
radar (InSAR) — measured, not modeled. Negative mm/year = sinking.

Agent-friendly pricing: **$0.40 per covered report, and misses are free**
(out-of-coverage, no-data, too-stale, and low-confidence results all cost $0).
Use `dry_run=True` for a free coverage + price check first.

## Install

```bash
pip install -U langchain-sibfly
export SIBFLY_API_KEY="sf_live_..."
```

Get a key with free starter credits at [sibfly.com](https://sibfly.com). Agents
can self-register with no human step:
`POST https://sibfly.com/api/v1/autonomous/register`.

## Usage

```python
from langchain_sibfly import SibflyGroundMotion

motion = SibflyGroundMotion()  # reads SIBFLY_API_KEY

# By address
print(motion.invoke({"address": "1100 Congress Ave, Austin, TX"}))

# By coordinates, free preview (no charge)
print(motion.invoke({"lat": 30.3244, "lon": -97.8102, "dry_run": True}))
```

Example result:

```python
{
    "status": "ok",
    "velocity_vertical_mm_yr": -6.0,
    "velocity_uncertainty_mm_yr": 1.5,
    "assessment_code": "notable_subsidence",
    "confidence": 0.86,
    "data_age_days": 73,
    "cost_usd": 0.4,
    "credits_remaining_usd": 0.6,
}
```

Route logic on `assessment_code` — one of `rapid_subsidence`,
`notable_subsidence`, `stable`, `mild_uplift`, `strong_uplift` — not on the
human-readable `assessment` string.

### Free gates (avoid paying for data you'd reject)

- `dry_run=True` — free coverage + `would_cost_usd`, no reading, no charge.
- `max_age_days=N` — if the newest data is older than N days, returns a free
  `stale_data` result instead of billing.
- `min_confidence=0.0..1.0` — below this pixel confidence, returns a free
  `low_confidence` result instead of billing.

## Use it in an agent

```python
from langchain_sibfly import SibflyGroundMotion
from langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic

agent = create_react_agent(
    ChatAnthropic(model="claude-sonnet-5"),
    tools=[SibflyGroundMotion()],
)
agent.invoke({"messages": [("user", "Is the ground sinking at 1100 Congress Ave, Austin TX?")]})
```

## Links

- API: <https://sibfly.com> · Docs: <https://sibfly.com/docs> · Agent docs: <https://sibfly.com/llms.txt>
- OpenAPI: <https://sibfly.com/openapi.json> · Machine schema: <https://sibfly.com/api/v1/schema>
- MCP server: `https://sibfly.com/mcp` (also in the official MCP registry as `com.sibfly/ground-motion`)

## License

MIT
