terraphim / terraphim/terraphim-ai

feat: Implement GenAgent trait framework (unblock terraphim_kg_agents)

Open
#535 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement multi-agent
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.rs
  • crates/terraphim_kg_agents/src/planning.rs
  • crates/terraphim_kg_agents/src/coordination.rs
Acceptance Criteria
  • GenAgent<S> trait defined with async lifecycle hooks
  • All three agent modules in terraphim_kg_agents uncommented and compiling
  • At least one integration test demonstrating a GenAgent lifecycle (init -> handle_call -> terminate)
  • Existing tests in terraphim_kg_agents pass

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.