Principia is a Python framework that turns public literature and private materials into traceable Idea Cards, priors, and validation-ready packs for research workflows.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (2 so far).
What it is
Principia is a local-first Python framework that turns public literature and private research materials into traceable Idea Cards, prior-art comparisons, and validation-ready research packs.
How it works
The project supports cross-domain retrieval from sources like arXiv/OpenAlex/Crossref/Semantic Scholar with identity reconciliation, private context ingestion for local documents, and structured extraction of typed ideas, principles, takeaways, comparators, evaluation contexts, and grounded result facts with provenance. It enables a staged workflow: retrieval, extraction, evidence selection, generation, and export, all in a configurable pipeline. The tool uses a three-stage generation process (scidialect-evo) and provides deterministic validation artifacts derived from the final Idea Card and evidence packet.
Getting started
Installation:
python -m pip install principia-ai==1.3.3
Add optional local/notebook support:
python -m pip install "principia-ai[local,notebook]==1.3.3"
Environment setup examples:
export SILICONFLOW_API_KEY="your-key"
export OPENALEX_API_KEY="your-openalex-key"
Quick start example shows creating a workspace with an LLM config and starting a research job using PipelineConfig.research(). It also demonstrates a private corpus option with allow_remote_private_content=True and explains that private documents are supplemental.
import os
import principia as pc
GOAL = (
"Develop an evidence-grounded method for improving long-horizon "
"reasoning efficiency in LLM agents under a fixed token budget."
)
ws = pc.Workspace.project(
"principia_project",
llm_config=pc.siliconflow_config(
os.environ["SILICONFLOW_API_KEY"],
max_calls=220,
),
)
job = ws.start(
GOAL,
pipeline_config=pc.PipelineConfig.research(),
)
result = job.result()
result.show()
Add a private corpus:
import os
import principia as pc
ws = pc.Workspace.project(
"principia_project",
llm_config=pc.siliconflow_config(
os.environ["SILICONFLOW_API_KEY"],
max_calls=220,
),
allow_remote_private_content=True,
)
job = ws.start(
"Your research objective",
documents="private_sources",
pipeline_config=pc.PipelineConfig.research(),
)
result = job.result()
result.show()
Recent releases
The latest release in the README is v1.3.3; no other releases are listed.
Traction
Stars: 413 Stars gained last 24h: 3
Behind the repo
Homepage points to GitHub repository pzqpzq/Principia and related docs; no startup/company information provided beyond project metadata.
Caveats
License: MIT (as shown in README), with Apache-2.0 listed in repo metadata. Documentation indicates Python 3.10–3.13 compatibility and a distribution named principia-ai. No explicit age beyond creation date 2026-06-09 and last_push 2026-07-20.