max / makenotwork

2.4 KB · 60 lines History Blame Raw

1	//! Kberg — MCP bridge for connecting local LLMs to desktop apps.
2	//!
3	//! Named after Königsberg, the city whose seven bridges founded graph theory
4	//! (Euler, 1736). The library is a bridge in that same sense: it routes
5	//! tool-call edges between an LLM node and a set of app nodes.
6	//!
7	//! # Shape
8	//!
9	//! - [`Tool`] + [`ToolRegistry`] — app-side action surface.
10	//! - [`resource::ResourceRegistry`] — app-side object surface: live things a
11	//! client lists and reads (deox exposes editor buffers this way).
12	//! - [`server`] — Streamable HTTP MCP server (JSON-RPC 2.0). Any MCP-speaking
13	//! client can reach a Kberg-served app.
14	//! - [`agent::Agent`] + [`agent::InferenceProvider`] — provider-agnostic
15	//! agent loop. Bring your own inference endpoint; Kberg does not manage
16	//! models or runtimes.
17	//! - [`provider::ollama`] — reference `InferenceProvider` for a local Ollama
18	//! server. Future providers (OpenAI, Anthropic, OpenAI-compatible) drop in
19	//! without touching the agent loop.
20	//!
21	//! # Guardrails
22	//!
23	//! - Every [`Tool`] declares [`ToolKind::Read`] or [`ToolKind::Write`] with a
24	//! named capability. Writes are the finite, app-declared vocabulary of
25	//! permissions the LLM can be granted — webhook-style.
26	//! - Arguments are validated against the tool's own `input_schema` before
27	//! dispatch ([`schema`]). Failures name the offending fields, so the agent
28	//! loop can hand the model a correctable diagnostic instead of prose.
29	//! - [`SurfaceProjection::Compact`] exposes only tools the app has annotated
30	//! as small-model safe.
31	//! - Hard refusals ([`Refusal`]) appear in `tools/list` with a stable reason
32	//! so models don't invent plausible names.
33	//!
34	//! # Design
35	//!
36	//! Design rationale and the roadmap for the planned primitives live as notes in
37	//! the maintainer wiki, bridged to this crate.
38	//! <!-- wiki: kberg-overview -->
39
40	pub mod agent;
41	mod error;
42	pub mod resource;
43	pub mod schema;
44	pub mod tool;
45
46	pub use agent::{Agent, AgentConfig, InferenceProvider, Message, Role, RunOutcome, ToolCall};
47	pub use error::{Error, Result};
48	pub use resource::{ResourceContents, ResourceDescriptor, ResourceRegistry};
49	pub use schema::{SlotError, SlotProblem};
50	pub use tool::{
51	ContentPart, Refusal, SurfaceProjection, Tool, ToolCallResult, ToolKind, ToolRegistry,
52	ToolSpec, WriteCapability,
53	};
54
55	#[cfg(feature = "server")]
56	pub mod server;
57
58	#[cfg(feature = "ollama")]
59	pub mod provider;
60