# soumyabrata2003/tripcraft architecture

> Architecture diagram of the GitHub repository soumyabrata2003/tripcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/soumyabrata2003/tripcraft
- Repository: https://github.com/soumyabrata2003/tripcraft

## Overview

TripCraft is a benchmark and research implementation for generating and assessing constraint-aware travel itineraries. Its main workflow uses a planner to turn a trip query, persona, and travel information into a natural-language plan; postprocessing converts plans to evaluation-format JSON, which is assessed with feasibility and continuous quality metrics. Supporting components provide travel-domain lookups, planning-time cost checks, and budget/query utilities. The repository excerpts show planner dependencies and evaluation data access; the README documents the plan-to-JSON and evaluation stages. Some subsystem links are omitted where the sampled source does not establish a caller.

Main entry points: [`evaluation/hard_constraint.py`](https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/hard_constraint.py) (Hard constraints), [`evaluation/commonsense_constraint.py`](https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/commonsense_constraint.py) (Commonsense constraints), [`utils/budget_estimation.py`](https://github.com/soumyabrata2003/tripcraft/blob/main/utils/budget_estimation.py) (Budget estimation), [`tools/planner/env.py`](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/env.py) (Planning cost checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Itinerary planning"]
  node_planner_runner["Planner runner"]
  node_planner["LLM planner<br/>[apis.py]"]
  node_prompts["Planner prompts<br/>[prompts.py]"]
  node_planning_environment["Planning cost checks<br/>[env.py]"]
end

subgraph group_travel_data["Travel information"]
  node_flights["Flight lookup<br/>[apis.py]"]
  node_accommodations["Accommodation lookup<br/>[apis.py]"]
  node_restaurants["Restaurant lookup<br/>[apis.py]"]
  node_attractions["Attraction lookup<br/>[apis.py]"]
  node_events["Event lookup<br/>[apis.py]"]
  node_distance["Distance lookup<br/>[apis.py]"]
end

subgraph group_processing["Plan processing"]
  node_postprocess["Plan postprocessor<br/>[openai_request.py]"]
  node_query_generation["Evaluation query generation"]
  node_evaluation_json["Evaluation-format plans"]
end

subgraph group_assessment["Plan assessment"]
  node_feasibility["Feasibility checks<br/>[eval.py]"]
  node_hard_constraints["Hard constraints<br/>[hard_constraint.py]"]
  node_commonsense["Commonsense constraints"]
  node_quality_metrics["Continuous quality metrics"]
end

subgraph group_utilities["Planning utilities"]
  node_budget["Budget estimation"]
  node_query_selection["Query element selection"]
  node_shared_functions["Parsing helpers<br/>[func.py]"]
end

node_traveler(("Trip request"))
node_language_model["Chat model"]

node_traveler -.->|"provides trip request"| node_planner_runner
node_planner_runner -->|"invokes"| node_planner
node_planner -->|"uses prompts"| node_prompts
node_planner -->|"uses environment"| node_planning_environment
node_planner -->|"queries"| node_language_model
node_planning_environment -->|"checks costs"| node_flights
node_planning_environment -->|"checks costs"| node_accommodations
node_planning_environment -->|"checks costs"| node_restaurants
node_planning_environment -->|"checks travel cost"| node_distance
node_planning_environment -.->|"checks itinerary"| node_attractions
node_planner_runner -.->|"submits plan"| node_postprocess
node_query_generation -->|"calls"| node_postprocess
node_postprocess -.->|"produces JSON"| node_evaluation_json
node_evaluation_json -->|"is evaluated by"| node_feasibility
node_feasibility -->|"runs checks"| node_hard_constraints
node_feasibility -->|"runs checks"| node_commonsense
node_evaluation_json -->|"is scored by"| node_quality_metrics
node_hard_constraints -->|"checks plan data"| node_flights
node_hard_constraints -->|"checks plan data"| node_accommodations
node_hard_constraints -->|"checks plan data"| node_restaurants
node_hard_constraints -->|"checks travel cost"| node_distance
node_hard_constraints -->|"checks plan data"| node_attractions
node_hard_constraints -->|"checks plan data"| node_events
node_commonsense -->|"checks itinerary"| node_flights
node_commonsense -->|"checks itinerary"| node_accommodations
node_commonsense -->|"checks itinerary"| node_restaurants
node_commonsense -->|"checks travel"| node_distance
node_commonsense -->|"checks itinerary"| node_attractions
node_commonsense -->|"checks itinerary"| node_events
node_budget -->|"estimates costs"| node_flights
node_budget -->|"estimates costs"| node_accommodations
node_budget -->|"estimates costs"| node_restaurants
node_budget -->|"estimates travel cost"| node_distance
node_budget -->|"estimates costs"| node_attractions
node_budget -->|"estimates costs"| node_events
node_query_selection -->|"uses estimates"| node_budget
node_query_selection -->|"uses lookup"| node_distance
node_hard_constraints -->|"uses parsing"| node_shared_functions
node_commonsense -->|"uses parsing"| node_shared_functions

click node_planner_runner "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/sole_planning_mltp.py"
click node_planner "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/apis.py"
click node_prompts "https://github.com/soumyabrata2003/tripcraft/blob/main/agents/prompts.py"
click node_planning_environment "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/env.py"
click node_flights "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/flights/apis.py"
click node_accommodations "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/accommodations/apis.py"
click node_restaurants "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/restaurants/apis.py"
click node_attractions "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/attractions/apis.py"
click node_events "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/events/apis.py"
click node_distance "https://github.com/soumyabrata2003/tripcraft/blob/main/tools/googleDistanceMatrix/apis.py"
click node_postprocess "https://github.com/soumyabrata2003/tripcraft/blob/main/postprocess/openai_request.py"
click node_query_generation "https://github.com/soumyabrata2003/tripcraft/blob/main/postprocess/generate_atp_query.py"
click node_evaluation_json "https://github.com/soumyabrata2003/tripcraft/blob/main/postprocess/sample_evaluation_format.jsonl"
click node_feasibility "https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/eval.py"
click node_hard_constraints "https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/hard_constraint.py"
click node_commonsense "https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/commonsense_constraint.py"
click node_quality_metrics "https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/qualitative_metrics.py"
click node_budget "https://github.com/soumyabrata2003/tripcraft/blob/main/utils/budget_estimation.py"
click node_query_selection "https://github.com/soumyabrata2003/tripcraft/blob/main/utils/query_element_selection.py"
click node_shared_functions "https://github.com/soumyabrata2003/tripcraft/blob/main/utils/func.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_planner_runner,node_planner,node_prompts,node_planning_environment toneBlue
class node_flights,node_accommodations,node_restaurants,node_attractions,node_events,node_distance toneAmber
class node_postprocess,node_query_generation,node_evaluation_json,node_traveler toneMint
class node_feasibility,node_hard_constraints,node_commonsense,node_quality_metrics toneRose
class node_budget,node_query_selection,node_shared_functions,node_language_model toneIndigo
```

## Components

### Itinerary planning

- [Planner runner](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/sole_planning_mltp.py): `tools/planner/sole_planning_mltp.py`
- [LLM planner](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/apis.py): `tools/planner/apis.py`
- [Planner prompts](https://github.com/soumyabrata2003/tripcraft/blob/main/agents/prompts.py): `agents/prompts.py`
- [Planning cost checks](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/planner/env.py): `tools/planner/env.py`

### Travel information

- [Flight lookup](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/flights/apis.py): `tools/flights/apis.py`
- [Accommodation lookup](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/accommodations/apis.py): `tools/accommodations/apis.py`
- [Restaurant lookup](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/restaurants/apis.py): `tools/restaurants/apis.py`
- [Attraction lookup](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/attractions/apis.py): `tools/attractions/apis.py`
- [Event lookup](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/events/apis.py): `tools/events/apis.py`
- [Distance lookup](https://github.com/soumyabrata2003/tripcraft/blob/main/tools/googleDistanceMatrix/apis.py): `tools/googleDistanceMatrix/apis.py`

### Plan processing

- [Plan postprocessor](https://github.com/soumyabrata2003/tripcraft/blob/main/postprocess/openai_request.py): `postprocess/openai_request.py`
- [Evaluation query generation](https://github.com/soumyabrata2003/tripcraft/blob/main/postprocess/generate_atp_query.py): `postprocess/generate_atp_query.py`
- [Evaluation-format plans](https://github.com/soumyabrata2003/tripcraft/blob/main/postprocess/sample_evaluation_format.jsonl): `postprocess/sample_evaluation_format.jsonl`

### Plan assessment

- [Feasibility checks](https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/eval.py): `evaluation/eval.py`
- [Hard constraints](https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/hard_constraint.py): `evaluation/hard_constraint.py`
- [Commonsense constraints](https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/commonsense_constraint.py): `evaluation/commonsense_constraint.py`
- [Continuous quality metrics](https://github.com/soumyabrata2003/tripcraft/blob/main/evaluation/qualitative_metrics.py): `evaluation/qualitative_metrics.py`

### Planning utilities

- [Budget estimation](https://github.com/soumyabrata2003/tripcraft/blob/main/utils/budget_estimation.py): `utils/budget_estimation.py`
- [Query element selection](https://github.com/soumyabrata2003/tripcraft/blob/main/utils/query_element_selection.py): `utils/query_element_selection.py`
- [Parsing helpers](https://github.com/soumyabrata2003/tripcraft/blob/main/utils/func.py): `utils/func.py`

### Other components

- **Trip request**
- **Chat model**

## Connections

- Trip request → Planner runner: provides trip request
- Planner runner → LLM planner: invokes (evidence: `tools/planner/sole_planning_mltp.py`)
- LLM planner → Planner prompts: uses prompts (evidence: `tools/planner/apis.py`)
- LLM planner → Planning cost checks: uses environment (evidence: `tools/planner/apis.py`)
- LLM planner → Chat model: queries (evidence: `tools/planner/apis.py`)
- Planning cost checks → Flight lookup: checks costs (evidence: `tools/planner/env.py`)
- Planning cost checks → Accommodation lookup: checks costs (evidence: `tools/planner/env.py`)
- Planning cost checks → Restaurant lookup: checks costs (evidence: `tools/planner/env.py`)
- Planning cost checks → Distance lookup: checks travel cost (evidence: `tools/planner/env.py`)
- Planning cost checks → Attraction lookup: checks itinerary (evidence: `tools/planner/env.py`)
- Planner runner → Plan postprocessor: submits plan
- Evaluation query generation → Plan postprocessor: calls (evidence: `postprocess/generate_atp_query.py`)
- Plan postprocessor → Evaluation-format plans: produces JSON (evidence: `README.md`)
- Evaluation-format plans → Feasibility checks: is evaluated by (evidence: `README.md`)
- Feasibility checks → Hard constraints: runs checks (evidence: `evaluation/eval.py`)
- Feasibility checks → Commonsense constraints: runs checks (evidence: `evaluation/eval.py`)
- Evaluation-format plans → Continuous quality metrics: is scored by (evidence: `README.md`)
- Hard constraints → Flight lookup: checks plan data (evidence: `evaluation/hard_constraint.py`)
- Hard constraints → Accommodation lookup: checks plan data (evidence: `evaluation/hard_constraint.py`)
- Hard constraints → Restaurant lookup: checks plan data (evidence: `evaluation/hard_constraint.py`)
- Hard constraints → Distance lookup: checks travel cost (evidence: `evaluation/hard_constraint.py`)
- Hard constraints → Attraction lookup: checks plan data (evidence: `evaluation/hard_constraint.py`)
- Hard constraints → Event lookup: checks plan data (evidence: `evaluation/hard_constraint.py`)
- Commonsense constraints → Flight lookup: checks itinerary (evidence: `evaluation/commonsense_constraint.py`)
- Commonsense constraints → Accommodation lookup: checks itinerary (evidence: `evaluation/commonsense_constraint.py`)
- Commonsense constraints → Restaurant lookup: checks itinerary (evidence: `evaluation/commonsense_constraint.py`)
- Commonsense constraints → Distance lookup: checks travel (evidence: `evaluation/commonsense_constraint.py`)
- Commonsense constraints → Attraction lookup: checks itinerary (evidence: `evaluation/commonsense_constraint.py`)
- Commonsense constraints → Event lookup: checks itinerary (evidence: `evaluation/commonsense_constraint.py`)
- Budget estimation → Flight lookup: estimates costs (evidence: `utils/budget_estimation.py`)
- Budget estimation → Accommodation lookup: estimates costs (evidence: `utils/budget_estimation.py`)
- Budget estimation → Restaurant lookup: estimates costs (evidence: `utils/budget_estimation.py`)
- Budget estimation → Distance lookup: estimates travel cost (evidence: `utils/budget_estimation.py`)
- Budget estimation → Attraction lookup: estimates costs (evidence: `utils/budget_estimation.py`)
- Budget estimation → Event lookup: estimates costs (evidence: `utils/budget_estimation.py`)
- Query element selection → Budget estimation: uses estimates (evidence: `utils/query_element_selection.py`)
- Query element selection → Distance lookup: uses lookup (evidence: `utils/query_element_selection.py`)
- Hard constraints → Parsing helpers: uses parsing (evidence: `evaluation/hard_constraint.py`)
- Commonsense constraints → Parsing helpers: uses parsing (evidence: `evaluation/commonsense_constraint.py`)
