contextgraph-host 0.1.0

Context Graph Protocol host runtime: provider discovery, stdio/http transports, capability negotiation, routing, consent gating. Usable by any Rust agent that wants Context Graph Protocol support.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# contextgraph-host

[![crates.io](https://img.shields.io/crates/v/contextgraph-host.svg)](https://crates.io/crates/contextgraph-host)
[![docs.rs](https://img.shields.io/docsrs/contextgraph-host)](https://docs.rs/contextgraph-host)

The host runtime for the **Context Graph Protocol**: provider discovery,
stdio + streamable-HTTP transports, capability negotiation, budget-honest
fan-out routing, and egress consent gating.

A Context Graph Protocol **host** is the side of the protocol that asks for context. `contextgraph-host`
is a ready-made host you can embed in any Rust agent: register providers
(in-process, a child process over stdio, or a remote HTTP endpoint), fan a
query out to all of them concurrently, and get back frames that passed
consent, a timeout, and a budget-honesty audit — a provider that lies about
its `token_cost` has its frames dropped and reported, never silently trusted.

Depends only on [`contextgraph-types`](https://crates.io/crates/contextgraph-types) plus
ordinary async/transport crates (`tokio`, `reqwest`) — no dependency on
[Stella](https://github.com/macanderson/stella) or any of its other crates.

## Example: query a stdio provider

```rust,no_run
use contextgraph_host::Host;
use contextgraph_types::ContextQuery;

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let mut host = Host::new();
host.add_stdio("docs", "contextgraph-example-docs", &[]).await?;

let query = ContextQuery {
    goal: "how do I configure it".into(),
    query_text: Some("configure".into()),
    embedding: None,
    kinds: vec![],
    anchors: vec![],
    max_frames: 8,
    max_tokens: 4096,
    as_of: None,
};

let fanout = host.query_all(&query).await;
for frame in fanout.accepted_frames() {
    println!("{} [{:.2}] {}", frame.citation_label.as_deref().unwrap_or(&frame.title), frame.score, frame.token_cost);
}
# Ok(())
# }
```

## Example: implement a provider

Any type that implements [`ContextProvider`] can be `host.register()`-ed as
an in-process provider — no child process or network hop required:

```rust
use async_trait::async_trait;
use contextgraph_host::{ContextProvider, HostError};
use contextgraph_types::{Capabilities, ContextQuery, ContextQueryResult, ProviderInfo};

struct MyProvider {
    info: ProviderInfo,
    capabilities: Capabilities,
}

#[async_trait]
impl ContextProvider for MyProvider {
    fn id(&self) -> &str { "my-provider" }
    fn info(&self) -> &ProviderInfo { &self.info }
    fn capabilities(&self) -> &Capabilities { &self.capabilities }

    async fn query(&self, query: &ContextQuery) -> Result<ContextQueryResult, HostError> {
        Ok(ContextQueryResult { frames: vec![], truncated: false, dropped_estimate: None })
    }
}
```

See [Implementing a provider][implementing] for the full guide, including the
stdio/HTTP transports (for providers written in *any* language, not just
Rust) and the consent-gating contract for `egress` providers.

## Docs

- [Protocol surface][protocol-surface] — the wire types this crate transports.
- [Implementing a provider][implementing] — the `ContextProvider` trait, the
  stdio/HTTP wire format, and the consent gate.
- [Running conformance][conformance] — proving your provider is conformant
  with `contextgraph-conformance`.
- [Stability][stability] — the crate-semver vs. protocol-version relationship.

[protocol-surface]: https://github.com/macanderson/context-graph-protocol/blob/main/docs/protocol-surface.md
[implementing]: https://github.com/macanderson/context-graph-protocol/blob/main/docs/implementing-a-provider.md
[conformance]: https://github.com/macanderson/context-graph-protocol/blob/main/docs/running-conformance.md
[stability]: https://github.com/macanderson/context-graph-protocol/blob/main/docs/stability.md
[`ContextProvider`]: https://docs.rs/contextgraph-host/latest/contextgraph_host/provider/trait.ContextProvider.html

## License

MIT OR Apache-2.0 — see [`LICENSE-MIT`](https://github.com/macanderson/stella/blob/main/LICENSE-MIT)
/ [`LICENSE-APACHE`](https://github.com/macanderson/stella/blob/main/LICENSE-APACHE)
in the workspace root.