terraphim / terraphim/terraphim-ai
feat: Implement GenAgent trait framework (unblock terraphim_kg_agents)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 62
- Forks
- 5
- Avg merge
- 2h 27m
- Merged PRs (30d)
- 1
Description
UPLIFT-2: Implement GenAgent trait framework
Source: medgemma-competition multi-agent integration plan
Priority: High (unblocks ~2,500 lines of disabled agent code)
Problem
terraphim_kg_agents has ~2,500 lines of agent code (worker, planning, coordination) that is ALL commented out in lib.rs because it references a non-existent terraphim_gen_agent crate and GenAgent<S> trait. The trait is conceptually similar to Erlang's gen_server but with typed state and async lifecycle hooks.
Proposed Change
Define GenAgent<S> trait in a new terraphim_gen_agent crate (or inside terraphim_agent_supervisor).
Minimum viable trait:
#[async_trait]
pub trait GenAgent<S: Send + Sync + 'static>: Send + Sync {
async fn init(&self) -> Result<S>;
async fn handle_call(&self, state: &mut S, msg: Box<dyn Any + Send>) -> Result<Box<dyn Any + Send>>;
async fn handle_cast(&self, state: &mut S, msg: Box<dyn Any + Send>) -> Result<()>;
async fn handle_info(&self, state: &mut S, info: SystemInfo) -> Result<()>;
async fn terminate(&self, state: &mut S, reason: ExitReason) -> Result<()>;
}
Then uncomment and fix the three agent modules in terraphim_kg_agents.
Files to Change
- New crate or addition to
crates/terraphim_agent_supervisor/ crates/terraphim_kg_agents/src/lib.rs(uncomment modules)crates/terraphim_kg_agents/src/worker.rscrates/terraphim_kg_agents/src/planning.rscrates/terraphim_kg_agents/src/coordination.rs
Acceptance Criteria
-
GenAgent<S>trait defined with async lifecycle hooks - All three agent modules in
terraphim_kg_agentsuncommented and compiling - At least one integration test demonstrating a GenAgent lifecycle (init -> handle_call -> terminate)
- Existing tests in
terraphim_kg_agentspass
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading crates/terraphim_kg_agents/src/lib.rs and the commented worker.rs, planning.rs, and coordination.rs modules, then inspect crates/terraphim_agent_supervisor/ for the proposed integration point. Define the trait and lifecycle types only after understanding those consumers. Done means all three modules compile, an integration test covers init → handle_call → terminate, and the existing terraphim_kg_agents tests pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- ai, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100