iTool.KnowledgeHub 4.0.0

iTool.KnowledgeHub

Business-neutral world knowledge primitives and AgentKernel tools.

The project intentionally fixes only the mechanics of a living world:

• WorldObservation enters the world;
• WorldIntent asks for a bounded view;
• KnowledgeContext and KnowledgeExplanation are consumer projections;
• EvolutionProposal lets an Agent submit a candidate without applying it;
• EvolutionCandidate records a data-driven proposed change;
• confidence decay retires stale links without deleting their evidence;
• conflicts can coexist, be resolved by selecting a link, and remain explainable;
• every mutation is revisioned and the reference runtime can roll back to an audited revision;
• IWorldEvolutionPolicy supplies learning behavior without adding business enums.

Predicates are opaque strings, so schema statements (for example, a relation describing a domain, range or inverse) use the same evidence-backed link model as every other world statement. No schema migration is required when a new vocabulary appears.

InMemoryWorldKnowledgeRuntime is a deterministic reference runtime for tests and simulations. Production hosts can replace it with an Orleans/DataFabric implementation without changing the agent-facing protocol.

For a repeatable learning/recall workload, WorldKnowledgeCorpusFactory.CreateReferenceCorpus() produces at least 1,000 small documents from 125 topic seeds spanning astronomy, physics, biology, earth science, mathematics, computing, language, history, geography, philosophy, art, music and other neutral world topics. DocumentKnowledgeIndex is a deliberately thin lexical projection: it stores the source text for recall, while one evidence-backed document observation is written to the same World runtime. The knowledge_learn_documents and knowledge_recall_documents AgentKernel tools use that projection without introducing a second fact model.

The synthetic corpus is only a deterministic regression fixture. For real, current information, WikimediaKnowledgeSource reads public Wikipedia summaries through the MediaWiki API and maps each page to a KnowledgeDocument with its page URL, revision id, retrieval time and reuse notice. Use FetchPagesAsync for a curated/reproducible title list, or FetchRandomAsync to sample the live encyclopedia (the default count is 1,000). Missing pages and transient HTTP/JSON failures are returned as diagnostics instead of being silently learned; only documents with non-empty extracts are admitted. A revision-aware document id keeps a later page revision as new evidence instead of overwriting the earlier snapshot.

var runtime = new InMemoryWorldKnowledgeRuntime();
var index = new DocumentKnowledgeIndex(runtime);
using var http = new HttpClient();
var source = new WikimediaKnowledgeSource(http);
var live = await source.FetchRandomAsync(new WikimediaKnowledgeSourceOptions
{
    Language = "en",
    Scope = "world",
    Count = 1_000,
    BatchSize = 20,
});
if (!live.ReachedRequestedCount)
    throw new InvalidOperationException($"Only fetched {live.ReturnedCount}/{live.RequestedCount} live pages.");

await index.LearnAsync(new KnowledgeDocumentBatch
{
    BatchId = $"wikimedia-{DateTimeOffset.UtcNow:yyyyMMdd}",
    RequestedBy = "live-source-agent",
    Documents = live.Documents,
});

Live material must retain the returned Source URL and License/SourceRevision fields and should be revalidated before publication. The source follows the public MediaWiki Action API model and does not turn web text into unverifiable synthetic facts.

To let an Agent perform this as one explicit effect, register AddWikimediaKnowledge(index, source). It exposes knowledge_fetch_wikimedia, which reports fetched/applied counts and every diagnostic; the Agent can then use the existing knowledge_recall_documents tool against the same index.

DailyWorldSimulationFactory supplies a seeded day-by-day stream for integration tests and demos: people encountered, places visited, objects noticed, sounds heard, transient signals, short information notes, and occasional contradictory reports. It emits ordinary WorldObservation records plus documents, so the same stream exercises learning, forgetting, conflict repair, emergent insight and recall. Change DailyWorldSimulationOptions.Seed to replay another trace.

var runtime = new InMemoryWorldKnowledgeRuntime();
var tools = KnowledgeAgentTools.Create(runtime);

// Register `tools` with iTool.AgentKernel. The agent can observe, understand, explain, propose and evolve
// the same world; it does not carry a second memory.

// Or use the thin builder extension:
// AgentKernel.CreateBuilder().AddWorldKnowledge(runtime);

var index = new DocumentKnowledgeIndex(runtime);
await index.LearnAsync(new KnowledgeDocumentBatch
{
    BatchId = "world-reference-v1",
    Documents = WorldKnowledgeCorpusFactory.CreateReferenceCorpus().ToList(),
});
var hits = await index.RecallAsync(new DocumentRecallRequest { Query = "photosynthesis plants" });
// hits.Hits[i].Context links each document back to its world observation/evidence.

The reference behavior is covered by tests/iTool.KnowledgeHub.Tests and can be run with:

dotnet test tests/iTool.KnowledgeHub.Tests/iTool.KnowledgeHub.Tests.csproj

The test suite includes a 1,000-document learn/replay/recall check and a scripted AgentKernel run that calls the document recall tool and verifies the returned evidence, plus a scripted learn-then-recall tool chain.

The reference quality gates are intentionally explicit: the corpus must have at least 1,000 unique documents across 30 or more topic families and two or more languages; replay must apply zero new observations; a ten-query labeled benchmark at K=8 must reach Precision@K and Recall@K of at least 0.90, MRR of at least 0.90, and evidence coverage of at least 0.99; stale links must retire while their evidence remains available; dense observations must yield at least two evidence-backed, stable insight candidates and an Agent run must be able to explain those candidates from derived evidence; a recall-only AgentKernel run must complete in no more than two tool rounds/two calls with no retries or failed tool results. RecallQualityEvaluator and AgentToolRunMetrics provide the reusable measurements behind these assertions.