Metadata-Version: 2.4
Name: cisco-project-quarry
Version: 0.1.0
Summary: Detection DSL for AI agents
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Requires-Dist: cachetools==7.2.0
Requires-Dist: google-re2==1.1.20251105
Requires-Dist: lark==1.3.1
Requires-Dist: loguru==0.7.3
Requires-Dist: orjson<4,>=3.11.6
Requires-Dist: packaging==26.3
Requires-Dist: pydantic==2.14.1
Requires-Dist: pygments>=2.21.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: rich==15.0.0
Provides-Extra: inference
Requires-Dist: aiohttp>=3.14.4; extra == 'inference'
Requires-Dist: anyio>=4.14.2; extra == 'inference'
Requires-Dist: boto3==1.43.118; extra == 'inference'
Requires-Dist: certifi>=2026.10.19; extra == 'inference'
Requires-Dist: filelock>=4.2.1; extra == 'inference'
Requires-Dist: httpx==0.28.1; extra == 'inference'
Requires-Dist: idna>=3.15; extra == 'inference'
Requires-Dist: jsonschema==4.26.0; extra == 'inference'
Requires-Dist: litellm==1.103.2; extra == 'inference'
Requires-Dist: multidict>=6.9.1; extra == 'inference'
Requires-Dist: python-dotenv>=1.2.4; extra == 'inference'
Requires-Dist: requests>=2.33.0; extra == 'inference'
Requires-Dist: urllib3>=2.8.0; extra == 'inference'
Provides-Extra: plugin
Requires-Dist: aiohttp>=3.14.4; extra == 'plugin'
Requires-Dist: anyio>=4.14.2; extra == 'plugin'
Requires-Dist: boto3==1.43.118; extra == 'plugin'
Requires-Dist: certifi>=2026.10.19; extra == 'plugin'
Requires-Dist: filelock>=4.2.1; extra == 'plugin'
Requires-Dist: httpx==0.28.1; extra == 'plugin'
Requires-Dist: idna>=3.15; extra == 'plugin'
Requires-Dist: jsonschema==4.26.0; extra == 'plugin'
Requires-Dist: litellm==1.103.2; extra == 'plugin'
Requires-Dist: mcp==2.3.0; extra == 'plugin'
Requires-Dist: multidict>=6.9.1; extra == 'plugin'
Requires-Dist: pyjwt>=2.15.0; extra == 'plugin'
Requires-Dist: python-dotenv>=1.2.4; extra == 'plugin'
Requires-Dist: requests>=2.33.0; extra == 'plugin'
Requires-Dist: urllib3>=2.8.0; extra == 'plugin'
Description-Content-Type: text/markdown

# Project Quarry

Project Quarry is a Python framework for detecting threats and behavior patterns in agent conversations. Write rules over messages, tool calls, tool results, and event order. You can also call a configured model adapter from a rule when local checks are not enough.

Quarry parses and validates rules when you load them, then compiles each rule to a symbolic finite-state automaton. A scan runs that compiled program over the conversation. Rules that cannot compile fail during loading.

Quarry is in alpha, and its DSL syntax may change before v1.0.0 in ways that require updates to existing rules.

## Features

- Text, regular expressions (RE2), structured-field, and tool use checks
- Multi-turn flow rules, captures, counts, and typed policy parameters
- Optional configured model scoring, classification, completion, token counting, and spans
- Witness evidence, explain output, and typed collections for supported rules
- Sync and async Python APIs, plus human, JSON, and CSV CLI output
- Explicit input, compile, time, and model-call limits

## Install

Quarry supports Python 3.11 through 3.13.

**Setup:**

```bash
git clone https://github.com/cisco-ai-defense/project-quarry.git
cd project-quarry
uv sync --frozen
```

Run `uv sync --frozen --extra inference` if your application uses a built-in model provider.

## Quick start

Scan an example conversation from the repository root:

```bash
uv run --frozen quarry scan --config examples/config.yaml --target examples/data/benign.json
```

`examples/config.yaml` selects fourteen local rules that run without model credentials.
Four semantic rules use deterministic keyword stubs via an explicit config opt-in;
these stubs are for examples and tests, not production decisions.
To see a match, scan `examples/data/tool_calls.json` with the same
config. You can also target `examples/data/` to scan every conversation file; a
successful scan with matches exits `1`. The full example rule collection is exercised
by `uv run --frozen python scripts/e2e_signature_test.py`, which supplies deterministic
model and prober implementations in process.

A YAML configuration file loads your own rules:

```yaml
config_version: 2
rules:
  - rules/
```

For example, save this rule as `rules/credential-request.rule`:

```text
rule "Credential request"
strings:
    $terms = ["api key", "access token"] nocase
condition:
    any msg in user_messages where msg.content contains_any $terms
```

Pass an OpenAI-shaped conversation as JSON with a `messages` array. The CLI exits `0` for a complete clean scan, `1` for a complete match, and `2` when the scan is invalid or incomplete.

## Python API

```python
from quarry import QuarryGuard

guard = QuarryGuard("config.yaml")
matches = guard.scan({"messages": [{"role": "user", "content": "Plan a picnic."}]})
for match in matches:
    print(match["rule"], match["metadata"])
```

`QuarryGuard` raises on incomplete scans. `DSLScanner` returns a `ScanResult` so you can inspect completion status, evidence, and typed outputs. `compile_policy` prepares one reusable parameterized rule.

## Documentation

- [Getting started](docs/getting-started.md)
- [How Quarry works](docs/how-quarry-works.md)
- [DSL guide](docs/dsl.md) and [generated language reference](quarry/language/reference.md)
- [Rule writing](docs/rule-writing.md) and [string matching](docs/string-matching.md)
- [Configuration](docs/configuration.md) and [message input](docs/messages.md)
- [Python API](docs/python-api.md) and [parameters](docs/parameters.md)
- [Model inference](docs/model-inference.md) and [application integration](docs/integration.md)
- [Agent plugin](docs/PLUGIN.md) for Codex, Claude Code, and MCP hosts
- [Architecture](docs/architecture.md) and [testing](docs/testing.md)
- [Synthetic examples](examples/README.md)

See [CONTRIBUTING.md](CONTRIBUTING.md) to work on Quarry. Report security issues through [SECURITY.md](SECURITY.md). Keep conversation data and credentials out of public issues.

## License

Distributed under the `Apache 2.0` License. See [LICENSE](LICENSE) for more
information.