{"id":50727698,"url":"https://github.com/kernelshreyak/knowledge_engine-problemsolver","last_synced_at":"2026-06-10T05:32:15.684Z","repository":{"id":334545968,"uuid":"1141720636","full_name":"kernelshreyak/knowledge_engine-problemsolver","owner":"kernelshreyak","description":"A general knowledge representation and querying system that helps understand relationships between concepts, simulate scenarios and find solutions to problems","archived":false,"fork":false,"pushed_at":"2026-01-25T13:07:39.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T04:21:50.792Z","etag":null,"topics":["falkordb","graphiti","graphrag","knowledge-discovery","knowledge-graph","knowledge-management","ontology-engineering","owl-ontology","rdf"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kernelshreyak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-25T10:04:12.000Z","updated_at":"2026-01-25T13:07:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kernelshreyak/knowledge_engine-problemsolver","commit_stats":null,"previous_names":["kernelshreyak/knowledge_engine-problemsolver"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kernelshreyak/knowledge_engine-problemsolver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kernelshreyak%2Fknowledge_engine-problemsolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kernelshreyak%2Fknowledge_engine-problemsolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kernelshreyak%2Fknowledge_engine-problemsolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kernelshreyak%2Fknowledge_engine-problemsolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kernelshreyak","download_url":"https://codeload.github.com/kernelshreyak/knowledge_engine-problemsolver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kernelshreyak%2Fknowledge_engine-problemsolver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34139178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["falkordb","graphiti","graphrag","knowledge-discovery","knowledge-graph","knowledge-management","ontology-engineering","owl-ontology","rdf"],"created_at":"2026-06-10T05:32:11.293Z","updated_at":"2026-06-10T05:32:15.671Z","avatar_url":"https://github.com/kernelshreyak.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Knowledge Engine  \n*A validated, ontology-driven knowledge backend for planning, simulation, and reasoning*\n\n📄 **White Paper (Design \u0026 Rationale)**  \n➡️ https://docs.google.com/document/d/1tEWRXAXDzJdT1Z1Z5D-zaWnx8w7es_qKYlQLpvO-fn4/edit?usp=sharing  \n\n\u003e **Recommended starting point**  \n\u003e The white paper explains *why* this system exists, the architectural choices behind it, and how it differs from naïve RAG, agentic systems, and auto-generated knowledge graphs.  \n\u003e  \n\u003e This repository is the **reference implementation** of that design.\n\n---\n\n## Overview\n\n**Knowledge Engine** is a modular backend component for building, validating, and querying a **governed knowledge graph**.\n\nIt is designed to plug into existing systems that need:\n- Accurate and auditable knowledge representation\n- Explicit lineage of changes\n- Deterministic graph-based retrieval (GraphRAG)\n- Ontology-driven structure without coupling the rest of the stack to a specific graph database\n\nThe system treats knowledge as a **managed asset**, not as an unverified byproduct of LLM generation.\n\n---\n\n## Why This Project Exists\n\nMost LLM-based systems today suffer from one or more of the following:\n\n- Hallucinations becoming persistent “knowledge”\n- No separation between extraction, inference, and authority\n- No audit trail for how facts entered the system\n- Tight coupling between prompts, storage, and retrieval\n- Poor suitability for high-trust domains (planning, simulation, analysis)\n\n**Knowledge Engine addresses these issues by design.**\n\n### Key Characteristics\n\n- **Validation-first workflow**  \n  New knowledge is always staged as a *validation object* before it can affect the KG.\n\n- **Versioned approvals**  \n  Regenerations create linked versions; validating one invalidates the rest.\n\n- **Ontology-driven extraction**  \n  LLMs must align proposed nodes and relationships to the active ontology.\n\n- **Relationship-aware retrieval (GraphRAG)**  \n  Queries are post-filtered by relation type  \n  (e.g. `DISCOVERED` for “What did X discover?”).\n\n- **Backend-friendly APIs**  \n  Exposed as clean REST endpoints callable from any service.\n\n- **Switchable storage backends**  \n  - SQLite for metadata  \n  - FalkorDB + Graphiti for the KG  \n  - Extensible to other graph databases\n\nThis makes the system suitable for **planning, wargaming, simulation, and decision-support workflows**.\n\n---\n\n## Relationship to the White Paper\n\nThe white paper describes:\n- The **problem statement** this system addresses\n- The **architecture and design principles**\n- The **knowledge lifecycle** (proposal → validation → persistence → retrieval)\n- How ontology definition enables reuse across domains\n- Why this approach differs from RAG and agentic pipelines\n\nThis repository implements those ideas concretely.\n\nIf you are evaluating or extending the system, **read the white paper first**.\n\n---\n## Run\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nuvicorn app.main:app --reload\n```\n\n## FalkorDB + Graphiti\n\nStart FalkorDB with persistence:\n\n```bash\ndocker-compose up -d\n```\n\nThe compose file mounts a named volume to persist the graph data directory and enables append-only persistence.\n\nSet env vars (see `.env.example`) and enable Graphiti:\n\n```bash\nexport KG_BACKEND=graphiti\nexport GRAPHITI_URI=falkor://localhost:6379\nexport GRAPHITI_GRAPH_NAME=knowledge_engine\n```\n\nThe API also loads `.env` automatically via `python-dotenv`.\n\nGraphiti requires an embeddings/LLM provider (for example `OPENAI_API_KEY`) depending on your setup.\n\nThe API loads `.env` from the project root automatically.\n\nOntology switching (via env):\n\n```bash\nexport ONTOLOGY_PATH=./ontologies_and_facts/ontology.md\n# or use the wargaming ontology\nexport ONTOLOGY_PATH=./ontologies_and_facts/wargaming_ontology.md\n```\n\n## Endpoints\n\n- POST `/knowledge-engine/ingest/text`\n- POST `/knowledge-engine/expand`\n- POST `/knowledge-engine/query/expand`\n- POST `/knowledge-engine/query/retrieve`\n- POST `/knowledge-engine/validation/{validation_id}/validate`\n- POST `/knowledge-engine/validation/{validation_id}/regenerate`\n- GET `/knowledge-engine/validation/{validation_id}`\n- GET `/knowledge-engine/validation/{validation_id}/image`\n- GET `/knowledge-engine/ontology`\n\n## Docs\n\n- `docs/overview.md`\n- `docs/ontology.md`\n- `docs/validation-workflow.md`\n- `docs/graphiti-falkordb.md`\n- `docs/api.md`\n- `docs/changes-retrieval-filtering.md`\n- `docs/ontology.md` (explains ontology switching)\n\n## API Usage\n\nIngest free text (creates a validation object):\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/ingest/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\":\"Marie Curie discovered radium.\"}'\n```\n\nExpand with LLM (creates a validation object placeholder):\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/expand \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\":\"Expand this knowledge about Marie Curie.\"}'\n```\n\nQuery to expand the KG (creates a validation object + query record):\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/query/expand \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\":\"Find related discoveries to radium.\"}'\n```\n\nRetrieve via GraphRAG (returns query record with results):\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/query/retrieve \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\":\"What did Marie Curie discover?\"}'\n```\n\nValidate a validation object (writes to KG when Graphiti is enabled):\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/validation/1/validate\n```\n\nRegenerate a validation object (creates a new version linked to the root):\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/validation/1/regenerate\n```\n\nFetch a validation object:\n\n```bash\ncurl http://localhost:8000/knowledge-engine/validation/1\n```\n\nFetch a validation object as PNG:\n\n```bash\ncurl http://localhost:8000/knowledge-engine/validation/1/image --output validation.png\n```\n\nFetch the ontology definition:\n\n```bash\ncurl http://localhost:8000/knowledge-engine/ontology\n```\n\n## Typical Flow\n\n1) Ingest or expand to create a validation object.\n2) Review the validation object (and optionally the image).\n3) Validate the version you want committed to the KG.\n4) Query the KG for retrieval (GraphRAG) or request expansions.\n\nExample flow:\n\n1) Ingest text\n\n```bash\ncurl -X POST \\\n  http://localhost:8000/knowledge-engine/ingest/text \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"text\":\"Marie Curie discovered radium.\"}'\n```\n\n2) View validation\n\n```bash\ncurl http://localhost:8000/knowledge-engine/validation/1\n```\n\n```bash\ncurl http://localhost:8000/knowledge-engine/validation/1/image --output validation.png\n```\n\n3) Validate (writes to KG when Graphiti is enabled)\n\n```bash\ncurl -X POST http://localhost:8000/knowledge-engine/validation/1/validate\n```\n\n4) Retrieve\n\n```bash\ncurl -X POST \\\n  http://localhost:8000/knowledge-engine/query/retrieve \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\":\"What did Marie Curie discover?\"}'\n```\n\n## Visualize the Graph (FalkorDB Browser)\n\nYou can use the FalkorDB Browser UI to explore the graph visually.\n\nOption A: Run FalkorDB + Browser together (quickest):\n\n```bash\ndocker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest\n```\n\nOpen http://localhost:3000 in your browser.\n\nOption B: Run Browser separately and connect to your FalkorDB server:\n\n```bash\ndocker run -p 3000:3000 -e FALKORDB_URL=redis://localhost:6379 falkordb/falkordb-browser:latest\n```\n\nYou can also try the hosted browser at https://browser.falkordb.com.\n\n## Ontology + LLM Extraction\n\nThe ontology is stored in `ontology.md` and loaded at runtime. To change it, edit the file directly.\n\nThe validation object is created by an LLM using LangGraph. Set an LLM provider env var, for example:\n\n```bash\nexport LLM_MODEL=gpt-4o-mini\nexport OPENAI_API_KEY=your_key_here\n```\n\n## Graphiti Data Notes\n\nGraphiti stores data as `Entity`, `Fact`, and `Episode` nodes inside the FalkorDB graph. Use the Browser to query those labels directly:\n\n```cypher\nMATCH (e:Entity) RETURN e LIMIT 25\n```\n\n```cypher\nMATCH (f:Fact) RETURN f LIMIT 25\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkernelshreyak%2Fknowledge_engine-problemsolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkernelshreyak%2Fknowledge_engine-problemsolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkernelshreyak%2Fknowledge_engine-problemsolver/lists"}